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Preface 



Organization 



This publication provides infonnation for system programmers about 
MVS/Extended Architecture Data Facility Product, and how to modify and extend 
the data management capabilities of the operating system. 



This publication contains the following chapters and appendixes: 

• Chapter 1, "Managing the Volume Table of Contents (VTOC)" on page 1, 
defines and discusses the structure of the VTOC and VTOC index, and the use 
of system macros to read a data set control block (DSCB), rename a data set, 
delete a data set from the VTOC, or obtain DASD volume free space 
information. 

• Chapter 2, "Executing Your Own Channel Programs (EXCP)" on page 63, 
defines and discusses the use of the EXCP macro to control the organization of 
data based on device characteristics with your own channel programs. 

• Chapter 3, "Reading from and Writing to Direct Access Devices (XDAP)" on 
page 99, defines and discusses the use of the XDAP macro to read, verify, and 
update blocks without using an access method. 

• Chapter 4, "Password Protecting Data Sets" on page 111, defines and 
discusses system password protection and how to create and maintain the 
PASSWORD data set. 

• The information formerly in Chapter 5, "Exit Routines" on page 125 has 
been moved to Data Facility Product: Customization. 

• Chapter 6, "System Macro Instructions" on page 127, defines and discusses 
the system macros used to refer to, validate, and modify system data areas. 

• Chapter 7, "Maintainmg SYSl.IMAGELIB" on page 203, defmes and 
discusses adding a UCS or FCB image to the system image library, and 
maintaining the UCS image tables. 

• Chapter 8, "JES2 Support for the ffiM 1403, 3203 Model 5, and 321 1 
Printers" on page 225, defines and discusses JES2 support for UCS alias 
names and the 321 1 indexing feature. 
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The information formerly in Chapter 9, "CATALOG, SCRATCH, and 
RENAME Dummy Modules" on page 227 has been moved to Data Facility 
Product: Customization. 

Chapter 10, "Specifying Buffer Numbers for DASD Data Sets" on page 229, 
defines and discusses the performance considerations when using the BUFNO 
keyword and subparameter. 

Appendix A, "CVAF VTOC Access Macros" on page 231, defines and 
discusses the format of the VTOC access macros: CVAFDIR, CVAFDSM, 
CVAFFILT, CVAFSEQ, and CVAFTST, and their return codes. 

Appendix B, "Examples of VTOC Access Macros" on page 259, defines and 
discusses examples of using the VTOC access macros in your programs. 

Appendix C, "VTOC Index Error Message and Associated Codes" on 
page 297, defines and discusses the error message and field codes issued by 
the Common VTOC Access Facility (CVAF). 

The information formerly in Appendix D, "Example of an OPEN Installation 
Exit Module" on page 305 has been moved to Data Facility Product: 
Customization. 

Appendix E, "DFP ISMF Services" on page 307, defines and discusses the 
DFP user services available with ISMF. 



Prerequisite Knowledge 



In order to use this book efficiently, you should be familiar with the following 
topics: 

• Assembler language 

• Standard program linkage conventions 

• The utility programs lEHLIST and lEHPROGM 

• Data management access methods and macro instructions 



Required Publications 



You should be familiar with the information presented in the following 
publications: 

• Assembler H Version 2 Application Programming: Language Reference, 
GC26-4037, and Assembler H Version 2 Application Programming: Guide, 
GC26-4036, contain more information on coding in assembler language. 

• MVS/ Extended Architecture System Programming Library: Supervisor Services 
and Macro Instructions, GC28-1 154, contains a description of standard linkage 
conventions. 
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• MVS /Extended Architecture Data Administration: Utilities, GC26-41 50, 
describes how to use lEHLIST to maintain the VTOC, and lEHPROGM to 
protect data sets. 

• MVS /Extended Architecture Data Administration Guide, GC26-4140, and 
MVS /Extended Architecture Data Administration: Macro Instruction Reference, 
GC26-4141, contain information on using access methods and macro 
instructions to do input and output. 

Specific prerequisite reading is listed at the beginning of some chapters, as it relates 
to the particular topic. 



Related Publications 



Within the text, references are made to the publications listed in the table below. 



Short Title 






(as it appears 






in the text) 


Publication Title 


Order Number 


Access Method 


MVS /Extended Architecture 


GC26-4135 


Services Reference 


Integrated Catalog 
Administration: Access Method 
Services Reference 

MVS /Extended Architecture 
VSAM Catalog Administration: 
Access Method Services Reference 


GC26-4136 


Assembler H V2 


Assembler H Version 2 


SC26-4036 


Application 


Application Programming: Guide 




Programming: 






Guide 






Assembler H V2 


Assembler H Version 2 


GC26-4037 


Application 


Application Programming: 




Programming: 


Language Reference 




Language 






Reference 






Checkpoint/Restart 


MVS /Extended Architecture 


GC26-4139 


User's Guide 


Checkpoint /Restart User's Guide 




Conversion 


MVS /Extended Architecture 


GC28-1143 


Notebook 


Conversion Notebook 




Data 


MVS /Extended Architecture Data 


GC26-4140 


Administration 


Administration Guide 




Guide 
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Short Title 






(as it appears 






in the text) 


Publicatioii Title 


Order Number 


Data 


MVS/ Extended Architecture Data 


GC26-4141 


Administration: 


Administration: Macro 




Macro Instruction 


Instruction Reference 




Reference 






Data Facility 


MVS /Extended Architecture Data 


GC26-4267 


Product: 


Facility Product: Version 2 




Customization 


Customization 




Debugging 


MVS /Extended Architecture 


LC28-11641 


Handbook 


Debugging Handbook, Volumes 1 


LC28-1165 




through 5 


LC28-.1166 
LC28-1167 
LC28-1168 


Device Support 


Device Support Facilities User's 


GC35-0033 


Facilities User's 


Guide and Reference 




Guide and 






Reference 






ffiM System/370 


IBM System/ 3 70 Principles of 


GA22-7000 


Principles of 


Operation 




Operation 






ffiM 2821 Control 


IBM 2821 Control Unit 


GA24-3312 


Unit Component 


Component Description 




Description 






ffiM 3203 Printer 


IBM 3203 Printer Component 


GA33-1515 


Component 


Description and Operator's Guide 




Description and 






Operator's Guide 






ffiM 3211 Printer, 


IBM 3211 Printer, 3216 


GA24-3543 


3216 


Interchangeable Train Cartridge, 




Interchangeable 


and 3811 Printer Control Unit 




Train Cartridge, 


Component Description and 




and 3811 Printer 


Operator's Guide 




Control Unit 






Component 






Description and 






Operator's Guide 






IBM 3262 Printer 


IBM 3262 Printer Model 5 


GA24-3936 


Model 5 Product 


Product Description 




Description 







Note: 

1 All five volumes may be ordered under one order number, LBOF-1015. 
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Short Title 
(as it appears 
in the text) 


Publication Title 


Order Number 


IBM 3800 Printing 
Subsystem 
Programmer's 
Guide 


IBM 3800 Printing Subsystem 
Programmer's Guide 


GC26-3846 


IBM 4245 Printer 
Model 1 
Component 
Description and 
Operator's Guide 


IBM 4245 Printer Model 1 
Component Description and 
Operator's Guide 


GA33-1541 


IBM 4248 Printer 
Description 


IBM 4248 Printer Description 


GA24-3927 


Initialization and 
Tuning 


MVS/ Extended Architecture 
System Programming Library: 
Initialization and Tuning 


GC28-1149 


JCL User's Guide 


MVS /Extended Architecture JCL 
User's Guide 


GC28-1351 


JCL Reference 


MVS /Extended Architecture JCL 
Reference 


GC28-1352 


JES2 Initialization 
and Tuning 


MVS /Extended Architecture 
System Programming Library: 
JES2 Initialization and Tuning 


SC23-0065 


JES3 Data Areas 


MVS /Extended Architecture Data 
Areas (MVS/JES3) 


LYB8-1195 


JES3 Initialization 
and Tuning 


MVS /Extended Architecture 
System Programming Library: 
JESS Initialization and Tuning 


SC23-0059 


Linkage Editor and 
Loader User's 
Guide 


MVS /Extended Architecture 
Linkage Editor and Loader User's 
Guide 


GC26-4143 


Magnetic Tape 
Labels and File 
Structure 
Administration 


MVS /Extended Architecture 
Magnetic Tape Labels and File 
Structure Administration 


GC26-4145 


Open/Close/EOV 
Logic 


MVS /Extended Architecture 
Open/Close/EOV Logic 


LY26-3966 


RACE General 
Information 


Resource Access Control Facility 
(RACE): General Information 
Manual 


GC28-0722 
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Short Title 
(as it appears 
in the text) 


Pubtication Title 


Order Number 


Service Aids 


MVS/ Extended Architecture 
System Programming Library: 
Service Aids 


GC28-1159 


Supervisor Services 
and Macro 
Instructions 


MVS /Extended Architecture 
System Programming Library: 
Supervisor Services and Macro 
Instructions 


GC28-1154 


System Generation 


MVS /Extended Architecture 
Installation: System Generation 


GC26-4148 


System Logic 
Library 


MVS /Extended Architecture 
System Logic Library: Volume 8 
o//7,Partsland2(IOS) 


LY28-1234 (Part 

1) 

LY28-1235 (Part 

2) 


System Macros and 
Facilities 


MVS /Extended Architecture 
System Programming Library: 
System Macros and Facilities, 
Volumes 1 and 2 


GC28-1150 
GC28-1151 


System Messages 


MVS /Extended Architecture 
Message Library: System 
Messages, Volumes 1 and 2 


GC28-1376 
GC28-1377 


TSO Command 

Language 

Reference 


MVS Extended Architecture TSO 
Command Language Reference 
(OS/VS2 TSO Command 
Language Reference, as updated 
by Supplement SD23-0259 for 
MVS/XA) 


GC28-0646 


TSO/E Data Areas 


MVS /Extended Architecture 
TSO/E Data Areas (plus 
Supplement LDB3-0276) 


LYB8-1119 


Utilities 


MVS / Extended Architecture Data 
Administration: Utilities 


GC26-4150 


VSAM 

Administration: 
Macro Instruction 
Reference 


MVS /Extended Architecture 
VSAM Administration: Macro 
Instruction Reference 


GC26-4152 
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Notational Conventions 



A uniform system of notation describes the format of data management macro 
instructions. This notation is not part of the language; it simply provides a basis for 
describing the structure of the commands. 

The command format illustrations in this book use the following conventions: 

Brackets [ ] indicate an optional parameter. 

Braces | ] indicate a choice of entry; unless a default is indicated, you must 
choose one of the entries. 

Items separated by a vertical bar ( | ) represent alternative items. No more 
than one of these items may be selected. 

An ellipsis (...) indicates that multiple entries of the type immediately preceding 
the ellipsis are allowed. 

Other punctuation (such as parentheses, commas, and spaces) must be entered 
as shown. A space is indicated by a blank. 

BOLDFACE type indicates the exact characters to be entered, except as 
described in the buUets above. Such items must be entered exactly as 
illustrated. 

Lowercase italic type specifies fields to be supplied by the user. 

BOLDFACE UNDERSCORED type indicates a default option. If the 
parameter is omitted, the underscored value is assumed. 

Parentheses ( ) must enclose subf ields if more than one is specified. If only 
one subfield is specified, you may omit the parentheses. 



Address and Register Conventions 



The following describes the meaning of each notation used to show how an 
operand can be coded: 

symbol 

The operand can be any valid assembler-language symbol. 



iO) 



O) 



General register can be used as an operand. When used as an operand in a 
macro instruction, the register must be specified as the decimal digit 
enclosed in parentheses as shown above. 



General register 1 can be used as an operand. When used as an operand in a 
macro instruction, the register must be specified as the decimal digit 1 
enclosed in parentheses as shown above. When you use register 1, the 
instruction that loads it is not included in the macro expansion. 
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(2-/2) 

The operand specified can be any of the general registers 2 through 12. All 
registers as operands must be coded in parentheses; for example, if register 3 
is coded, it is coded as (3). When one of the registers 2 through 12 is used, it 
can be coded as a decimal digit, symbol (equated to a decimal digit), or an 
expression that results in a value of 2 through 12. 

RX-Type Address 

The operand can be specified as any valid assembler-language RX-type 
address. The following shows examples of each valid RX-type address: 

Name Operation Operand 



ALPHAl 


L 


1,39(4,10) 


ALPHA2 


L 


REG 1,39(4, TEN) 


BETAl 


L 


2,ZETA(4) 


BETA2 


L 


REG2,ZETA(REG4) 


GAMMAl 


L 


2,ZETA 


GAMMA2 


L 


REG2,ZETA 


GAMMAS 


L 


2,=F1000' 


LAMBDAl 


L 


3,20(,5) 



Both ALPHA instructions specify explicit addresses; REGl and TEN have 
been defined as absolute symbols. Both BETA instructions specify implied 
addresses, and both use index registers. Indexing is omitted from the 
GAMMA instructions. GAMMAl and GAMMA2 specify implied 
addresses. The second operand of GAMMA3 is a literal. LAMBDAl 
specifies an explicit address with no indexing. 

A-Type Address 

The operand can be specified as any address that can be written as a valid 
assembler-language A-type address constant. An A-type address constant 
can be written as an absolute value, a relocatable symbol, or relocatable 
expression. Operands that require an A-type address are inserted into an 
A-type address constant during the macro expansion process. For more 
details about A-type address constants, see Assembler H Version 2 
Application Programming: Language Reference. 

absexp 

The operand can be an absolute value or expression. An absolute expression 
can be an absolute term or an arithmetic combination of absolute terms. An 
absolute term can be a nonrelocatable symbol, a self -defining term, or the 
length attribute reference. For more details about absolute expressions, see 
Assembler H Version 2 Application Programming: Language Reference. 
OS/VS-DOS/VSE- VM/3 70 Assembler Language. 

relexp 

The operand can be a relocatable symbol or expression. A relocatable 
symbol or expression is one whose value changes by n if the program where 
it appears is relocated n bytes away from its originally assigned area of 
storage. For more details about relocatable symbols and expressions, see 
Assembler H Version 2 Application Programming: Language Reference. 
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Summary of Changes 



I Release 3.0, Jwie 1987 



I Enhancements and New Support 



Data sets may now be retained beyond the year 1999 or be retained indefinitely 
(never-scratch). "Deleting a Data Set from the VTOC (SCRATCH and CAMLST 
SCRATCH)" on page 33 describes never-scratch designations. 

Information about the new LSPACE macro instruction has been added. 
Chapter 1, "Managing the Volume Table of Contents (VTOC)" on page 1, 
explains how to use the LSPACE macro to determine the amount of free space and 
the degree of space fragmentation on a direct access volume. The LSPACE macro 
also allows you to obtain VTOC status information. 

Open, Close, and End-of- Volume parameter lists may now reside at an address 
above 16 megabytes. Chapter 2, "Executing Your Own Channel Programs 
(EXCP)" on page 63 explains the changes to the EOV macro format and 
description in support of parameter lists above 16 megabytes. 

The retrieval area for information extracted from a JFCB can now be allocated at 
an address above 16 megabytes. Chapter 6, "System Macro Instructions" on 
page 127 now includes the following information in support of the retrieval area 
above 16 megabytes. 

• The differences in the RDJFCB and OPEN macro operands and parameter 
lists. 

• The new X' 1 3 ' exit list entry code. 

• The use of the IHAARL macro. 

Information related to customizing the Data Facility Product for individual users 
has been moved to Data Facility Product: Customization^ a new book. This includes 
the information in Chapter 2 under "Appendages" on page 71, all of Chapter 5 
(including the new information about the conventions that installation- written 
DADSM preprocessing and postprocessing modules must follow for 31 -bit versus 
24-bit addressing), all of Chapter 9, and the example formerly in Appendix D. 



Summary of Changes XI 



Service changes have been made throughout the manual, and are indicated in the 
text by revision bars. 



Release 2.0, June 1986 

Enhancements and New Support 

Information has been added for support of CVAF Filter Services. 

• The format of the CVPL in Chapter 1, "Managing the Volume Table of 
Contents," has been updated. 

• Appendix A now contains the CVAFFDLT macro syntax and explains the 
parameters, register contents, and return codes. 

• Appendix B now contains an example of a CVAFFILT invocation. 
Information has been added for support of DASD Calculation Services. 

• Chapter 5, "Exit Routines," describes the use of the DASD Calculation 
Services precalculation and postcalculation installation exits. It also explains 
the parameters, register contents, and return codes. 

Appendix E has been added to provide interface information for DFP/ISMF 
services. 

Chapter 1, "Managing the Volume Table of Contents," has been reorganized and 
rewritten. 

Chapter 7, "Maintaining SYSl.IMAGELIB," has been reorganized and rewritten. 

Service changes have been made throughout the manual, and are indicated in the 
text by revision bars. 



Release 1.0, April 1985 



Enhancements and New Support 



The SCRATCH and CAMLST SCRATCH macro descriptions have been updated 
to include support for the erasure of residual DASD data. 

Information has been added to the description of the REALLOC macro for 
DADSM support of DFDSS that: 

• Describes the new support and explains what it does. 

• Adds new keywords. 
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• Adds new return codes. 

The PARTREL macro has been added to the partial release section that: 

• Describes the new support and explains what it does. 

• Adds all keywords and descriptions. 

• Adds new return codes. 

Information supporting the ERASE-ON-SCRATCH option for RACF-defined 
data sets has been added to "Deleting a Data Set from the VTOC (SCRATCH and 
CAMLST SCRATCH)" on page 33. 

Information has been added to Figure 29 on page 134 to support the: 

• 3262 Model 5 Printer. 

• 4245 Printer. 

• 4248 Printer. 

Information has been added to support the IBM 3380 (all models). 

The following IBM 3480 Magnetic Tape Subsystem support information has been 
added: 

• The high-speed positioning feature. 

• Chapter 6, "System Macro Instructions" on page 127, has been updated. 

• The MSGDISP macro has been added to permit loading a message display on 
the 3480. 

• The 3480 has been added to Figure 29 on page 134. 



Summary of Changes Xlll 



"High-Speed roM 3480 Positioning" on page 149 in Chapter 6, "System Macro 
Instructions" on page 127 has been added and describes how to set the tape block 
ID for the IBM 3480 Magnetic Tape Subsystem in full function mode. 

Chapter 1, fonneriy titled "Controlling Space on DASD Volumes," has been 
renamed, "Managmg the Volume Table of Contents (VTOC)." 

Version 2 Publications 

The Preface includes new order numbers for Version 2. 
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Chapter 1. Managing the Volume Table of Contents (VTOC) 



The direct access device storage management (DADSM) routines control allocation 
of space on direct access volumes through the volume table of contents (VTOC) of 
that volume, and through the VTOC index if one exists. This chapter gives an 
overview of the VTOC and the VTOC index and discusses how to use system 
macros to access the VTOC and VTOC index. 



The VTOC 



The VTOC is a data set on a direct access volume that describes the contents of 
that volimie. It resides in a single extent (that is, it is a continuous data set) 
anywhere on the volume after cylinder 0, track 0. Its address is located in the 
VOL VTOC field of the standard volume label (see Figure 1 on page 2). 
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Standard Volume Label 



11(B) 

VOLVTOC (10 bytes) 
CCHHR of first 
record in VTOC 



it 




VTOC Data Set 
(Can be located anywhere 
on the volume after 
cylmder 0, track 0.) 



Figure 1. Locating the Volume Table of Contents (VTOC) 



The VTOC is composed of HO-byte^ data set control blocks (DSCBs) that 
correspond either to a data set or VSAM data space currently residing on the 
volume, or to contiguous, unassigned tracks on the volume. DSCBs for data sets or 
data spaces describe their characteristics. DSCBs for contiguous, unassigned tracks 
indicate their location. 



The 140 bytes are defined as a 44-byte key portion followed by a 96-byte data 
portion. You may make references to the logical 140-byte DSCB or to either of its 
parts. 
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Data Set Control Block (DSCB) Format Types 



Fonnat-O DSCB 



The VTOC has seven different kinds of DSCBs. This section lists the different 
kinds of DSCBs, what they are used for, how many exist on a volume, and how 
they are found. 

The first record in every VTOC is the VTOC (format-4) DSCB that describes (1) 
the device that the volume resides on, (2) the attributes of the volume itself, and 
(3) the size and contents of the VTOC data set itself. 

The format-4 DSCB is followed by a free-space (format-5) DSCB that, for a 
nonindexed VTOC, lists the extents on the volume that have not been allocated to 
a data set or VSAM data space. Each format-5 DSCB contains 26 extents. If 
there are more than 26 available extents on the volume, another format-5 DSCB 
will be built for every 26 extents. The format-5 DSCBs are chained, using the last 
field of each format-5 DSCB. An indexed VTOC does not use format-5 DSCBs 
for describing free space; however, one empty format-5 DSCB is provided to allow 
a basis for converting back to a nonindexed VTOC. 

The third and subsequent DSCBs in the VTOC have no prescribed sequence. 

A data set or VSAM data space is defined by one or more DSCBs in the VTOC of 
each volume on which it resides. The number of DSCBs needed to define a data 
set or VSAM data space is determined by (1) the organization of the data set 
(ISAM data sets need a format-2 DSCB to describe the index) and (2) the number 
of extents the data set or VSAM data space occupies (a format-3 DSCB is needed 
to describe the 4th through the 16th extents; additional fonnat-3 DSCBs may be 
required to describe the extents for a VSAM data set cataloged in an Integrated 
Catalog Facility catalog). Figure 2 on page 7 shows the general makeup of a 
VTOC and the DSCBs needed to define two types of data sets (ISAM and 
non-ISAM). 

Data set A (in Figure 2 on page 7) is an ISAM data set; three DSCBs, a format- 1, 
format-2, and format-3, are identified. Data sets B, C, and D could be sequential, 
partitioned, or direct data sets or they could be VSAM data spaces. Data set B has 
more than three extents and therefore requires both a format- 1 and a fonnat-3 
DSCB. 

Data sets C and D have three or fewer extents and need only a format- 1 DSCB. 
The format-6 DSCB, pointed to by the format-4 DSCB, is used to keep track of 
the extents allocated in order to be shared by two or more data sets (split-cylinder 
data sets). For example, if data sets C and D share an extent made up of one or 
more cylinders, this extent would be described in the fonnat-6 DSCB. Note that 
split-cylinder data sets cannot be allocated, but existing split-cylinder data sets can 
stUl be processed. 



Name: Free VTOC Record 

Function: Describes an unused record in the VTOC (contains 140 bytes of binary 
zeros). To delete a DSCB from the VTOC, a format-O DSCB is written over it. 
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Fonnat-l DSCB 



Format-! DSCB 



Foniiat-3 DSCB 



How Many: One for every unused 140-byte record on the VTOC. The 
DS4DSREC field of the format-4 DSCB is a count of the number of format-0 
DSCBs on the VTOC. This field is not mamtained for an indexed VTOC. 

How Found: Search on key equal to X'OO' (sometimes X'OOOOOOOO') for a 
nonindexed VTOC; for an indexed VTOC, the VTOC map of DSCBs is used to 
fmd a format-O DSCB. 



Name: Identifier 

Function: Describes the first three extents of a data set or VSAM data space. 

How Many: One for every data set or data space on the volume, except the 
VTOC. 

How Found: Search on key equal to the data set name. For an indexed VTOC, a 
CCHHR pointer for each data set name is in the VTOC index. 



Name: Index 

Function: Describes the indexes of an ISAM data set. 

How Many: One for every ISAM data set (for a multivolume ISAM data set, a 
format-2 DSCB exists only on the first volume). 

How Found: Chained from a format- 1 DSCB that represents the data set. 



Name: Extension 

Function: Describes the 4th through 16th extents of a data set or VSAM data 
space. Data sets and VSAM data spaces are restricted to 16 extents per volimie. 
VSAM data sets cataloged in an Integrated Catalog Facility catalog may be 
extended to a maximum of 123 extents, in which case there may be as many as ten 
format-3 DSCBs. 

How Many: One for each data set or VSAM data space on the volume that has 
more than three extents. There may be as many as ten for a VSAM data set 
cataloged in an Integrated Catalog Facility catalog. 

How Found: Chained from a format-2 or a format- 1 DSCB that represents the 
data set or VSAM data space. In the case of a VSAM data set cataloged in an 
Integrated Catalog Facility catalog, the chain may be from a preceding format-3 
DSCB. 
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Foniiat-4 DSCB 



Fonnat-S DSCB 



Fonnat-6 DSCB 



Name: VTOC 

Function: Describes the extent and contents of the VTOC and provides volume 
and device characteristics. If the VTOC is indexed, certain fields of this DSCB are 
not maintamed by DADSM. See "Structure of an Indexed VTOC." 

How Many: One on each volume. 

How Found: VOLVTOC field of the standard volume label contains its address. It 
is always the first record in the VTOC. 



Name: Free Space 

Function: On a nonindexed VTOC, describes the space on a volume that has not 
been allocated to a data set or to a VSAM data space (available space). For an 
indexed VTOC, format-5 is zero, and the volume pack space map describes the 
available space. 

How Many: One for every 26 noncontiguous extents of available space on the 
volume for a nonindexed VTOC; for an indexed VTOC, there is only one. 

How Found: The first format-5 DSCB on the volume is always the second DSCB 
of the VTOC. If there is more than one format-5 DSCB, it will be chained from 
the previous fonnat-5 DSCB via the DS5PTRDS field of each fonnat-5 DSCB. 



Name: Shared Extent 



Function: 

extents). 



Describes the extents shared by two or more data sets (split-cylinder 



How Many: One for every 26 split-cylinder extents on the VTOC. 

How Found: The address of the first fonnat-6 DSCB is contained in the 
DS4F6PTR field of the format-4 DSCB. If there is more than one format-6 DSCB 
on the volume, it will be chained from the previous format-6 DSCB via the 
DS6PTRDS field of the format-6 DSCB. 



Allocating and Releasing DASD Space 



The DADSM allocate and extend routines assign tracks and cylinders on direct 
access volumes for new data sets and VSAM data spaces. The DADSM extend 
routine obtains additional space for a data set or VSAM data space that has already 
exceeded its original, primary allocation. The DADSM scratch and partial release 
routines are used to release space that is no longer needed on a direct access 
volume. 

The DADSM routines allocate and release space by adding, deleting, and 
modifying the DSCBs. When space is needed on a volume, the allocate routmes 



Chapter 1. Managing the Volume Table of Contents (VTOC) 5 



search the appropriate DSCBs for enough contiguous, available tracks to satisfy the 
request. If there are not enough contiguous tracks, the request is filled, using as 
many as five noncontiguous groups of free tracks. The appropriate DSCBs are 
modified to reflect the assignment of the tracks. 

When space is released, the scratch routines free the DSCBs of the deleted data set 
or data space. For a nonindexed VTOC, to indicate that the tracks containing the 
affected data set or data space can be reallocated, a free space (format-5) DSCB is 
built (or modified if existent). For an indexed VTOC, the index is updated. 
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Standard Volume Label 
J J 



■^^ 



11(B) 
VOLVTOC 

field 



VTOC Data Set 



Data Set A 



Data Set B 



Format-4 DSCB 

Description of 
device, volume, 

and the VTOC . 

extent I 



d[»u m A 



First F5 DSCB 

Description of 
26 available 
extents 



d 



FosmmMDSCfi 



the date Hrt«iid 






M 



^Format-l DSCB 

T -Wi 

^Description of /^ 

^the data set and '//^^ 

^W.% first 3 extents; 



JFormat-6_pSCB 

Description of 
as many as 26 
shared-cylinder 
extents 



Next F5 DSCB 






Description of 
as many as 26 
available exents 



Data Set C 



'^Format-S DSCB 



-3 DSCB^ ^For 



^Description of 
^the 4th - 16th 
^extents of 
^data set B ^ 



Vy. 



rmat-1 DSCB 



/^ i;;^ Description of 



P 

;;;^data set C and 

//its first 3 extents 



Data Set D 



Bllilliili 



<Utai«tA 



^ormat-l_pSCB^ 

^Description of vZ' 
^the data set and v/^ 
'^^ts first 3 extent^^ 

m//////Mm. 



■^f- 



■^v 




DSCB for an ISAM 
data set (Data Set A) 




DSCB for a non-ISAM 
data set (Data Sets B, C, D) 
or a VSAM data space 



Note: Empty boxes in the VTOC data set represent free VTOC Records (Format-0 DSCBs) 



Figure 2. Contents of VTOC— DSCBs Describing Data Sets 
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The VTOC Index 



The VTOC index is a physical-sequential data set, residing on the same volume as 
the VTOC. It contains an index of data set names of format- 1 DSCBs in the 
VTOC and free space infonnation. The index is searched instead of the hardware 
keys. 

The VTOC index is optional. You may build it when you initialize the volume, or 
for an existing VTOC (with the volume online or offline). You may subsequently 
inactivate it (online or offline) so that the VTOC is processed without using the 
index. 

Each VTOC index is formatted by Device Support Facilities with physical blocks 
2048 bytes in length. These physical blocks are the VTOC index records (VDfls), 
the basic structural units of the index. The kind of information they contain 
depends on the part of the index they belong to. 

Several different kinds of records, each built from one or more VIRs, are in a 
VTOC index: 

• The VTOC index entry record (VffiR) that is used to access format- 1 DSCBs 
and the format-4 DSCB 

• The VTOC pack space map (VPSM) that shows what space has been allocated 
on a disk pack 

• The VTOC index map (VDCM) that shows which VIRs have been allocated in 
the VTOC index 

• The VTOC map of DSCBs (VMDS) that shows which DSCBs have been 
allocated in the VTOC 



An Example of a VTOC and Its Index 



A format- 1 DSCB in the VTOC contains the name and extent information of the 
VTOC index. The name of the index must be • SYS l.VTOCDC.xxxxxxxx', where 
'xxxxxxxx' can be anything valid in a data set name and is generally the serial 
number of the volimie containing the VTOC and its index. The name must be 
unique within the system to avoid ENQ contention. The relationship of a VTOC 
to its index is shown in Figure 3 on page 9. Each of the components of the index 
is discussed separately in the following sections. 
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VTOC 






VTOC Index 


Format-4 DSCB 






VIXM 


Format-5 DSCB 


VPSM 


Other DSCBs 


VMDS 


VIER 


VIER 


Format-1 DSCB for the VTOC 
Index: SYS1 .VTOCIX.nnn 






VIER 


Other DSCBs 




• 



Figure 3. Relationship of a VTOC to Its Index 



The VTOC Index Entry Record (VIER) 

VIERs have these characteristics: 



Contents of VIER Fields 



A VIER uses one VIR and contains variable-length index entries. The number 
of VIERs in an index varies depending upon the number of data sets on the 
volume. 

VEERs in a VTOC index may be on one or many levels. All index entries in a 
VEER are at the same index level. VIERs have a hierarchic relationship. Index 
entries in higher-level VIERs point to lower-level VIERs. Index entries in 
level-one VIERs (those at the lowest level) point to format-1 DSCBs for data 
sets on the volume. 

A higher-level VIER is created when the fourth lower-level VDER is created. 
When that new higher-level VIER is filled with pointers to lower-level VIERs, 
a new VIER at the same level is created. Again, when the fourth VEER at the 
same level is created, a VIER at a still higher level is created, adding another 
level to the index. 



Each VIER contains a header and sections (see Figure 4 on page 10). The VEER 
header contains: 

• A field identifying the VTOC index record as a VEER. 

• The relative byte address (RBA) of the VEER. 

• A pointer to a VEER at the same level (hence, a "horizontal" pointer). The 
VEER pointed to contains index entries whose keys are greater than any key in 
the pointmg VIER. 
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• The level number (LVL) of this VIER. 

• The number (SECNO) of sections (a VTER contains eight sections). 

• The length (SECL) of the sections (each section is 246 bytes in length). 

• The offsets to the first-used and the last-used sections. 

• The 44-byte high key of the VEER. 
Each section contains: 

• An offset to the last entry in the section (or zero if the section is empty) 

• Index entries 











0(00) 


EBCDIC Characters 'VIER' 






kiok) 


RBA of This VIER 




8(08) 


Horizontal Pointer 




12(0C) 


Old Horizontal Pointer 




16(10) 


LVL 


FLGl 


Reserved 


Index 
Header 


aod^*) 


PTRL 


SECNO 


SECL 


24(18) 


Offset to First-Used Section 




28(1C) 


Offset to Last-Used Section 




32(20) 


Highest Key In This VIER 




76('»C) 


Section 1 


. 




• 


8 Sections 
Contain ing 
Index Entries 




Section 8 





Figure 4. Format of the VTOC Index Entrj- Record (VIER) 
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Format of a VTOC Index Entry 

The format of an index entry is: 



When a VIER Is Created 



FLG 


KEYL 


Unused 


Record Pointer 


Key 



NAME OFFSET BYTES DESCRIPTION 

VXEFLG 00(00) 1 Flag byte 

VXEKEYL 01(01) 1 Length of the VXEKEY field 

VXEFC 02(02) 1 Unused 

VXERPTR 03(03) A or 5 Record pointer 

VXEKEY 07(07) 1 to kk Name of a data set, if a 

or level-one VIER; if not, the 

08(08) high key in the header of a 

lower- level VIER 



Each index entry contains: 

• A flag byte. 

• A keylength field (containing a value of 1 to 44, depending on the length of the 
data set name). 

• A record pointer (VXERPTR) that is one of the following: 

- In level-one VIERs, the 5-byte CCHHR of the format- 1 or format-4 
DSCB that represents the data set whose name is the key in the entry 

— In other VIERs, the 4-byte RBA of the lower-level VIER whose high key 
is the key in the entry 

• A key that, for level 1 VIERS, is the data set name, and for level 2 or higher 
VIERs is the high key of a lower-level VIER. Trailing blanks are suppressed in 
the VTOC index entry. 



The first level-one VIER is created when the VTOC index is created. Subsequent 
VIERs are created when a data set name is to be added to the VTOC index but the 
VIER where it should be added is full. A new VIER is created in the following 
manner: 

• A new VIER is allocated. 

• Half of the sections from a full VIER (those containing the highest keys) are 
moved into the new VIER, leaving each VIER half empty. 

• The new index entry is added to one of the two VIERs, depending on its key. 
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A Tree of Linked VIERs 



Figure 5 on page 13 shows how VIERS are related to each other. Note that the 
VIERs (which are simplified here — only the high key is shown in the header) form 
a type of "tree structure." 



How to Find a Format- 1 DSCB 



In the search for the format- 1 DSCB for a particular data set, one path along the 
tree structure is followed. 

As seen in Figure 4 on page 10, a field in the header of a VIER contains the 
highest key of any index entry in that VIER. Beginning with this field in the first 
high-level VIER, the following search logic is used: Is the key of the data set (the 
data set name) lower than or equal to the VIER's high key? If neither, the test is 
again applied with the VIER having a greater high key pointed to by the horizontal 
pointer. This procedure continues until a VIER is found having a high key that is 
greater than or equal to the key of the data set. Comparisons are then made with 
the entries in the VIER's sections. Eventually, an entry is found with a key greater 
than or equal to the data set key. This entry points to a VIER at the next-lower 
level. 

The search proceeds to successively lower levels until an entry in a level-two VIER 
is found whose key is greater than or equal to the key of the data set. This entry 
points to a level-one VIER that, in turn, contains an entry with a key that is equal 
to the data set key and that points to the format- 1 DSCB for the desired data set. 



Special Cases in a DSCB Search 



If there is only one level in the VTOC index, the entries in the VIERs all point to 
format- 1 DSCBs, so that only one level need be searched. 

If an update to the VTOC index requires a new VIER and the update is interrupted 
(for example, because of an I/O error or a system failure), the entry in the level-n 
VIER may contain a key that is greater than the high key in the lowertlevel VIER 
pointed to by that entry. In this case, two VIERs at level n-1 may have to be 
searched. This situation is corrected when D ADSM next processes the volume. 



The VTOC Pack Space Map (VPSM) 



The VPSM accounts for space on a disk pack. It shows what space on the volume 
has been allocated and what space remains free. 

The map contains bit maps of the cylinders and tracks on the volume. A value of 
one indicates that the cylinder or track has been allocated; a value of zero, that it 
has not been allocated. The bit representing a cylinder is set to zero if no tracks on 
the cylinder have been allocated; it is set to one if any track has been allocated. 
Tracks assigned as alternate tracks are marked as allocated. 

The VPSM replaces the chain of format-5 DSCBs, but one empty format-5 DSCB 
is left in the VTOC to allow for conversion back to a nonindexed VTOC, a process 
that requires reconstruction of a format-5 DSCB chain. 
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High Key 



Entries < 



VIER 



M32107.LIB 



B41103.TEST 
M32107.LIB 



VIER 



B41103.TEST 



44X'04' 

A11307.CLIST 

B0102.DATA 



VIER 



M32107.LIB 



C0102.ASM 
M32107.LIB 



Format-1 DSCBs 
in the VTOC 



H^ Format-4 DSCB in the VTOC 



VIER 



44X'FF' 



SYS1.MACLIB 
44XTF' 



VIER 



SYS1.MACLIB 



Level-2 
' VIERs 



VIER 



44X'FF' 



SYS1.VT0CIX.A 

X.Y.Z. 

44X'FF' 



Level -1 
VIERs 



Dummy Last 
— entry m 
VTOC index 



Figure 5. Structure of Linked VIERs 



The format of an index map (including the VPSM) is shown in Figure 6 on 
page 14. 
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00(00) 


ID of This Map 


04(04) 


RBA of This Map 


08(08) 


Horizontal Pointer to Next VIR 


12(0C) 


Sequence Number of First Entry 


16(10) 


VRFDA 


VRFO 


20(14) 


FLG1 


LUF1 


LUOF 


24(18) 


Size of Large Unit Map 


28(1C) 


SUFI 


SUBIT 


SUOF 


32(20) 


Size of Small Unit Map 


36(24) 


Reserved 


VIR 


40(28) 


RBA of First High-level VIER 




Large Unit Map 
(VTOC Pack Space Map Only) 




Small Unit Map 




VTOC Recording Facility Data 
(VTOC Index Map Only) 



F^ure 6. An Index Map 



The VTOC Index Map (VIXM) 



The VIXM contains a bit map in which each bit represents one VTOC index record 
(VIR). The status of the bit indicates whether the VIR is allocated (1) or 
unallocated (0). 

An area of the VIXM is reserved for VTOC recording facility (VRF) data. (This is 
the facility that allows detection of and recovery from certain errors in an indexed 
VTOC.) 

A field in the first VIXM record points to the first high-level VIER. Another field 
in the first VIXM record (VIR in Figure 7 on page 15) contains the number of 
VTOC index records that contain all the space maps. 
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The VTOC Map of DSCBs (VMDS) 



The VMDS contains a bit map where each bit represents one DSCB in the VTOC. 
The status of the bit indicates whether the DSCB is allocated (1) or unallocated 
(0). 



Name 


Offset 


Bytes 


Description 


VIMAP 


OO(X'OO') 


2048 


VTOC map 


VIMH 


OO(X'OO') 


44 


VTOC map header 


VIMID 


OO(X'OO') 


4 


Map ID in EBCDIC (»VPSM', 
•VIXM',or'VMDS') 


VIMRBA 


04(X'04') 


4 


RBA of this map 


VIMHZPTR 


08(X'08') 


4 


Horizontal RBA pointer to next VIR 
of this map 



VIMORG 12(X'0C') 4 

VIMVRFDA 16(X'10') 2 

VIMVRFO 18(X'12') 2 

VIMFLGl 20(X'14') 1 

VIMVRFSW X'80' 

.xxxxxxx 

VIMLUFl 21(X'15') 1 

VIMLUOF 22(X'16') 2 

VIMLUSZ 24(X'18') 4 



Sequence number of the first entry in 
the map 

Offset to current VRF data (if 
VIMVRFSW=1) or offset where VRF 
data may be written (if 
VIMVRFSW=:0), (first VIXM only) 

Offset to VRF area (first VDCM VIR 
only) 

Flag byte 

VRF data exists if 1 

Reserved 

Large unit flag byte 

Offset into VIR of large unit map 
(zero if none) 

Size in bits of large unit map 



Figure 7 (Part 1 of 2). Fonnat of a VTOC M^» 
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Name 



Offset 



Bytes 



Description 



VIMSUFl 28(X'1C') 1 

VIMSUBIT 29(X'1D') 1 

VIMSUOF 30(X'1E') 2 

VIMSUSZ 32(X'20') 4 

36(X'24') 3 

VIMVIR 39(X'27') 1 

VIMFHLV 40(X'28') 4 

VIMLUMAP 44(X'2C') kk 



VIMSUMAP mm 



VIMVRF pp 



mi 



qq 



Small unit flag byte 

Number of small unit bits per large 
unit (zero if none) 

Offset into VIR of small unit map 

Size in bits of small unit map 

Reserved 

Number of map records (VDCM only) 

RBA of first high-level VffiR (VDCM 
only) 

Large unit map (kk is VIMLUSZ/8, 
rounded up) 

Small unit map (mm is VIMSUOF, nn 
is VIMSUSZ/8, rounded up) 

VRF area (pp is VIMVRFO, qq is 
remainder of first VDCM) 



Figure 7 (Part 2 of 2). Format of a VTOC Map 



Structure of an Indexed VTOC 



An indexed VTOC is identical to a nonindexed VTOC, except that, for an indexed 
VTOC, only a single format-5 DSCB exists and is empty, and certain format-4 
DSCB data (the number of format-0 DSCBs and the CCHHR of the highest 
format- 1 DSCB) is not maintained by DADSM. The DOS bit (bit in field 
DS4VTOCI), set to one in the fonnat-4 DSCB, indicates that these fields (and the 
format-5 DSCB) cannot be relied on. The index bit (bit 7 in field DS4VTOCI) is 
set in the format-4 DSCB; it indicates that a VTOC index exists. 



Scratch/Rename/ Allocate Restrictions 



A VTOC index data set may not be scratched if the VTOC index is active. Neither 
may a VTOC index data set be renamed if the VTOC index is active, unless it is 
being renamed to another name beginning with 'SYSl.VTOCDC.'. A data set may 
not be renamed to a name beginning with 'SYSl.VTOCDC.* if there is already such 
a data set on the volume. Only one data set whose name begins with 
•SYSl.VTOCDC.* may be allocated on a volume. 
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Initializing and Maintaining the VTOC 



Creating the VTOC and VTOC Index 



To prepare a volume for use (to initialize it), the Device Support Facilities utility is 
used. One of the things this utility does is to build the VTOC. After initialization, 
this VTOC wm contain a format-4 DSCB and a fonnat-5 DSCB. For a 
nonindexed VTOC, the format-5 DSCB contains an extent entry for all the free 
space on the volume; the initial number of extents in the format-5 DSCB is one or 
two, depending on where the VTOC is located on the volume. If the VTOC is 
located somewhere other than at the beginning or end of the volume, two extent 
entries are needed to describe the free space that precedes and follows it. For an 
indexed VTOC, the format-5 DSCB contains a zero. 

A VTOC index can be created when a volume is initialized by using the Device 
Support Facilities command INIT and specifjdng the INDEX key word. 

A nonindexed VTOC can be converted to an indexed VTOC by using the 
command BUILDIX and specifying the IXVTOC ke5rword. The reverse is also 
possible by using the BUILDIX command and specifying the OSVTOC keyword. 

For more detailed information, see Device Support Facilities User's Guide and 
Reference. 



Protecting the VTOC and VTOC Index 



Resource Access Control Facility (RACE) 



You can protect the VTOC and VTOC index by using the Resource Access 
Control Facility (RACF). This is done by defining the volume serial entity under 
the RACF class DASDVOL. A user must be authorized to the 
DASD VOL/ volume serial entity at the following levels: 

• At the UPDATE level, to open the VTOC for output processing. 

• At the UPDATE level, to open for output processing any data set whose name 
begins with 'SYSl.VTOCIX.'. 

• At the ALTER level, to allocate, rename, or scratch any data set whose name 
begins with 'SYSl.VTOCIX.'. 

• At the ALTER level, to rename a data set to any name that begins with 
'SYSl.VTOCIX.'. 

Neither the VTOC nor the VTOC index is protected from being opened for input 
processing by the DASD VOL/volume serial entity. 

Note that neither the VTOC nor the VTOC index can be protected through the 
RACF class DATASET. 
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Authorized Prc^pram Facility (APF) Requirements 



Password Protection 



A program must be authorized by the authorized program facility (APF) to 
perform any of the following functions: 

• Opening a VTOC for output processing 

• Opening for output processing a data set whose name begins with 
•SYSl.VTOCIX.' 

• Allocating, renaming, or scratching any data set whose name begins. with 
•SYSl.VTOCIX.' 

• Renaming a data set to any name that begins with 'SYSl.VTOCIX.' 



The VTOC index data set may be password protected. The protection is the same 
as for any password-protected data set. Password checking is bypassed if the 
volume in which the VTOC index resides is protected by RACF through the 
DASDVOL class. 



Copying/Restoring/Initializiiig the VTOC 



Operations on Volumes Containing a Nonindexed VTOC 



Restoring a Volume from a Dump Tape. There are no operational requirements 
if you change the volume serial number or do a partial restore that does not 
modify the VTOC. If you do a restore and change the VTOC size vtdthout 
changing the volume serial number, the volume must be varied offline after it is 
restored. You should not do a restore on a volume with an indexed VTOC. 

Copying a Volume. There are no operational requirements if you change the 
volume serial number or do not modify the VTOC of the receiving volume. If 
you do a copy and change the VTOC size without changing the volume serial 
number, the volume must be varied offline after it is copied. You should not 
do a copy from a volume with an indexed VTOC. 



Operations on Volumes Containing an Indexed VTOC 



You should use Device Support Facilities to convert a VTOC to a nonindexed 
format to update the volume. If you do not, take note of the following 
information: 

• Initializing a Volume. If you do not change the volume serial number, the 
volume should be varied offline before starting the job. 

• Restoring a Volume from a Dump Tape. There are no operational requirements 
if you change the volume serial number or do a partial restore that does not 
modify the VTOC or VTOC index. If you do a restore and modify the VTOC 
or VTOC index without changing the volume serial number, the volume should 
be varied offline after it is restored. 
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Copying a Volume. There are no operational requirements if you change the 
volume serial number of the receiving volume or do a partial dump without 
modifying the VTOC or VTOC index. If you modify the VTOC or VTOC 
index without changing the volume serial number, the receiving volume should 
be varied offline after it is copied. 

Shared DASD Considerations. In shared DASD environments, whenever the 
VTOC index is modified or relocated or whenever the volume is changed from 
indexed VTOC to OS VTOC or from OS VTOC to indexed VTOC, the device 
should be varied offline to the sharing system or systems. 



Accessing the VTOC with DADSM Macros 



You may use DADSM or CVAF to access the VTOC and its index. (CVAF access 
is described in "Accessing the VTOC and its Index with CVAF Macros" on 
page 42.) DADSM macros and associated tasks include: 

LSPACE - Obtain free space, volume fragmentation, and VTOC 
status information for a DASD volume. 
■ OBTAIN - Read a DSCB from a VTOC. 

PARTREL - Release unused space from a SAM or PAM data set. 

REALLOC - DASD space allocation. 

RENAME - Rename a non-VSAM data set. 

SCRATCH - Release all space and DSCBs for a non-VSAM data set, 

The PARTREL macro is described in "Releasing Unused Space from a DASD 
Data Set" on page 169. The REALLOC macro is described in "Allocating a 
DASD Data Set" on page 174. 

This section tells how to use the LSPACE, OBTAIN, SCRATCH, and RENAME 
macro instructions. These macros are most commonly used by the operating 
system and the data set utility programs (lEHMOVE, CEBCOPY, and 
lEHPROGM), but you may use them in your own routines. The functions you can 
perform with these macros are: 

LSPACE Obtaining free space, volume fragmentation, and VTOC status 

information for a DASD volume 

OBTAIN Reading a data set control block from the VTOC 

RENAME Changing the name of a data set 

SCRATCH Deleting a data set 

You can obtain free space, volume fragmentation, and VTOC status information 
for a DASD volume by using the LSPACE macro instruction. LSPACE returns 
information to any of three user-specified areas. 

You can read a data set control block (DSCB) into virtual storage by using the 
OBTAIN and CAMLST macro instructions. There are two ways to specify the 
DSCB that you want to read: by using the name of the data set associated with the 
DSCB, or by using the absolute track address of the DSCB. You must provide a 
140-byte data area in virtual storage, into which the DSCB is to be read. When 
you specify the name of the data set, an identifier (format- 1 or format-4) DSCB is 
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read into virtual storage. To read a DSCB other than a format- 1 or a format-4 
DSCB, you must specify an absolute track address (see "Example" on page 32). 

You can change a data set name by usmg the RENAME and CAMLST macro 
instructions. This causes replacement of the data set name in the data set's 
format- 1 DSCB with the new name. 

You can delete a non-VSAM data set by using the SCRATCH and CAMLST 
macro instructions. This causes deletion of the data set's DSCBs. 



Coding examples, programming notes, and exception return code descripti 
accompany the following macro instruction descriptions. 



ions 



Note: You cannot use LSPACE, OBTAIN, SCRATCH, or RENAME macro 
instructions with either a SYSIN or SYSOUT data set. 



Obtaining DASD Volume Information (LSPACE) 



You can use the LSPACE macro to obtain free space, volume fragmentation, and 
VTOC status information for a DASD volume. LSPACE normally returns status 
information (such as LSPACE subfunction, return code, and reason code) to the 
parameter list. The format of the LSPACE parameter list is shown in Figure 8 on 
page 24. You may request that LSPACE return additional information such as the 
total number of free extents on the volume, or the fragmentation index. This 
additional information can be returned in either: 

• A message return area: "Message Return Area" on page 27 describes the 
format and content of the message return area. 

• A data return area: "Data Return Area" on page 27 describes the format and 
content of the data return area. 

• A Format-4 DSCB return area: "Format 4 DSCB Return Area" on page 28 
describes the format and content of the Format-4 DSCB return area. 

The format of the LSPACE macro is: 



\symbol\ 


LSPACE 


{\}CB^\addr\(regm 
\,MSG^{addr\(reg)\Q\ 
\l}X1X={addr\(reg)\m 
l,SMF=|rESl 1 YFS 1 NONEH 
[,F4DSCB=M</r | (reg) \ 0}1 
I,MF=U 1 D 1 (D,MSG) 1 (D,DATA) 
|L|(L,MSG)|(L,DATA) 
1 {E,addr) 1 {E,(regm\ 



y}C^=\addr\(reg)\ 

specifies the address of the UCB for the volume whose free space 
information you are requesting. 

addr — RX-type address 

specifics the address of a fullword that contains the address of the 
UCB. 
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(reg^2-12) 

specifies a register containing the UCB address for the device. 

When using the standard (MF=I) form of the macro, you must provide a 
UCB address. 

MSG^\addr | (reg) \ 0] \ DAT A=\addr \ (reg) \ 0} 

specifies the way LSPACE is to return free space information. 

Note: The MSG and DATA parameters are mutually exclusive. 

MSG=^{addr\(reg)\0] 

specifies the address of a caller-provided 30-byte message return area 
into which LSPACE returns either a free space message or, for 
unsuccessful requests, status information. For a description of this 
area, see "Message Return Area" on page 27. 

addr — RX-type address 

specifies the address of the message return area. 

iregh-(2-12) 

specifies a register containing the address of the message return 
area. 



specifies that you do not want the free space message. This is 
the default for all forms of the macro except execute. 

l>KlK^{addr\(reg)\ii\ 

specifies the address of a caller-provided 36-byte data return area into 
which LSPACE returns free space and volume information. For a 
description of this area, see "Data Return Area" on page 27. 

addr— -RX-type address 

specifies the address of the data return area. 

{reg)—(2-12) 

specifies a register containing the address of the data return 
area. 



specifies that you do not want the free space and volume 
information. 

SMF=frEST I YES | NONE} 

specifies the type of SMF processing desired. 

TEST 

specifies that LSPACE is to test for an SMF system and whether SMF 
volume information is desired. Only programs executing in supervisor 
state, protect key 0- 7, or APF-authorized may specify this operand. 
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YES 

specifies that you want LSPACE to provide SMF volume information. 
Only programs executing in supervisor state, protect key 0-7, or 
APF-authorized may specify this operand. 

NONE 

specifies that you do not want LSPACE to provide SMF volume 
information. This is the default for all forms of the macro except 
execute. 

F4DSCB=Mfr | (reg) \ OJ 

specifies the address of a 96-byte DSCB return area provided by the calling 
program, into which LSPACE returns the volume's format-4 DSCB. For a 
description of the format-4 DSCB fields, see the DSCB4 data area section in 
Debugging Handbook. 

addr — RX-type address 

specifies the address of the fonnat-4 DSCB return area. 

iregy^l-U) 

specifies a register containing the address of the format-4 DSCB 
return area. 



specifies that you do not want the data portion of the format-4 DSCB 
for the volume. This is the default for all forms of the macro except 
execute. 

MF={I I D I (D,MSG) I (D,DATA) | L | (L,MSG) | (L,DATA) | iV.,addr) \ {E,(regm 
specifies the form of the LSPACE macro. 



specifies the inline (standard) form of the macro. This generates an 
inline parameter list containing the required variables, loads the 
address of the parameter list in register 1, and issues an SVC 78. This 
form is the default. 



D 



generates a DSECT that maps the LSPACE parameter list. See 
Figure 8 on page 24 for the format of the LSPACE parameter list. 



(D,MSG) 

generates a DSECT that maps the message return area. For the 
format of the area, see "Message Return Area" on page 27. 

(D,DATA) 

generates a DSECT that maps the data return area. For the format of 
the area, see "Data Return Area" on page 27. 



L 



generates the required constants in the calling program. You may then 
issue the execute form of the macro, which uses these constants. 
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(L,MSG) 

generates the required message return area constants in the calling 
program. 

(L,DATA) 

generates the required data return area constants in the calling 
program. 

(E,addr) 

loads the address of the parameter list specified by addr into register 1, 
puts the specified variables into the parameter list, and issues an SVC 
78. 

(E,(reg)) 

loads the address of the parameter list specified by (reg) into register 1, 
puts the specified variables into the parameter list, and issues an SVC 
78. 
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Name 


Offset 


Bytes 


Description 


LSPAPL 








LSPAPLID 


OO(X'OO') 


4 


EBCDIC 'LSPA' 


LSPANGTH 


04(X'04») 


2 


Length of parameter list 


LSPAFLAG 


06(X'06') 


1 


Parameter flag byte 


LSPASMFY 




X'SO' 


SMF=YES 


LSPASMFT 




X'40' 


SMF=rEST 


LSPADATA 




X'20' 


Free space data request 


LSPARSVB 




...xxxxx 


Reserved 


LSPARSVD 


07(X'07') 


1 


Reserved 


LSPAERCD 


08(X'08') 


1 


LSPACE return code 


LSPASFID 


09(X'09') 


1 


LSPACE subfunction 


LSPASFPC 




X'OO' 


Processing complete 


LSPASFVP 




X'Ol' 


Validate parameters 


LSPASFUS 




X'02' 


Check UCB status 


LSPASFNQ 




X'03' 


Enq on SYSZDMNT 


LSPASF45 




X'04' 


Read F4 and first F5 (EXCP) 


LSPASFN5 




X'05' 


Read next F5 (EXCP) 


LSPASFRV 




X'06' 


Read vohime label (EXCP) 


LSPASF4X 




X'SO' 


Read F4 and maps (CVAFDIR) 


LSPASFEX 




X'81' 


Get free extents (CVAFDSM) 


LSPASFFO 




X'82' 


Get FO count (CVAFDSM) 


LSPASFVR 




X'83' 


Get VIR count (CVAFDSM) 


LSPASFVD 




X'84' 


Check for VRF (CVAFVRF) 


LSPASFRT 


lO(X'OA') 


1 


Subfunction return code 


LSPASFRS 


ll(X'OB') 


1 


Subfunction reason code 


LSPARSOl 




X'Ol' 


Check parameter list storage key 


LSPARS02 




X'02' 


Check parameter list ID 


LSPARS03 




X'03' 


Check LSPACE flag 


LSPARS04 




X'04' 


Check authorization for SMF flag 


LSPARS05 




X'05' 


Check message or data return area storage key 


LSPARS06 




X'06' 


Check f ormat-4 DSCB return area storage key 


LSPARS07 




X'07' 


Check UCB address 


LSPARS08 




X'08' 


Check for virtual UCB address 


LSPARS09 




X'09' 


Check for zero VTOC pointer 


LSPAUCB 


12(X'0C') 


4 


UCB address 


LSPAFRSP 


16(X'10') 


4 


Address of message or data return area 


LSPAFMT4 


20(X'14') 


4 


Address of format-4 DSCB 



Figure 8. Format of the LSPACE Parameter List (MF=D) 



Note: For more information about the LSPAERCD, LSPASFID, LSPASFRT, and 
LSPASFRS fields, see "LSPACE Status Information" on page 26. 
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Return Codes from LSPACE 

Return codes from LSPACE are as follows: 



Code Meaning 

(X ' 00 ' ) Successful processing 

4(X'04') Permanent I/O Error 

8(X'08') Non-Standard OS Volume 

12(X»0C ' ) Invalid Parameter or UCB Not Ready 

1 6 (X ' 1 ' ) Invalid Parameter List 
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I LSPACE Status Information 



Register and the LSPACE macro's parameter list^ contain additional diagnostic 
information. Figure 9 shows the relationship between the following LSPACE 
parameter list fields: 

• LSPAERCD (return code) 

• LSPASFID (subfunction identifier) 

• LSPASFRT (subfunction return code) 

• LSPASFRS (subfunction reason code) 



LSPAERCD LSPASFID 


LSPASFRT 


LSPASFRS 


Description 


16(X'10«) 


Ol(X'Ol') 


1 N/A 


01 (X'Ol') 


Bad parm list storage key 


16(X'10') 


Ol(X'Ol') 


N/A 


02 (X'02') 


Bad parm list ID 


12 (X'OC 


) Ol(X'Ol') 


N/A 


03 (X'03') 


InvaUd LSPACE flag 


12 (X'OC 


) Ol(X'Ol') 


► N/A 


04 (X'04') 


Not authorized for SMF 


12 (X'OC 


) 01 (X'Ol'] 


1 N/A 


05 (X'05') 


Bad MSG/DATA area storage key 


12 (X'OC 


) 01 (X'Ol') 


► N/A 


06 (X'06') 


Bad FMT4 area storage key 


12 (X'OC 


) 01 (X'Ol') 


1 N/A 


07 (X'07') 


UCB not found 


12 (X'OC 


) 01 (X'Ol') 


1 N/A 


08 (X'08') 


UCB not direct access device 


12 (X'OC 


) 01 (X'Ol') 


) N/A 


09 (X'09') 


UCB VTOC pointer is zero 


12 (X'OC 


) 02 (X'02') 


1 N/A 


N/A 


Invalid UCB status 


12 (X'OC 


) 03 (X'03') 


) ENQ RETC 


N/A 


Failed ENQ on SYSZDMNT 


08 (X'08') 


04 (X'04') 


1 N/A 


N/A 


F5s are invalid 


04(X'04') 


04 (X'04': 


1 ECB STAT 


N/A 


Error reading F4 and first F5 


04 (X'04') 


05 (X'OS') 


1 ECB STAT 


N/A 


Error reading next F5 


04(X'04') 


06(X'06'; 


1 ECB STAT 


N/A 


Error reading volume label 


04 (X'04') 


80(X'80': 


) DIR RETC 


CVSTAT 


Error getting F4/space maps 


04 (X'04') 


81 (X'81': 


1 DSM RETC 


CVSTAT 


Error getting free extents 


04 (X'04') 


82 (X'82'^ 


) DSM RETC 


CVSTAT 


Error getting FO count 


04 (X'04') 


83 (X'83'' 


) DSM RETC 


CVSTAT 


Error getting VIR count 


04 (X'04') 


1 84 (X'84' 


) VRFRETC 


CVSTAT 


Error checking for VRF 


OO(X'OO') 


00 (X'OO'. 


) N/A 


N/A 


No problems 



Figure 9. LSPACE Status Information Relationships 



LSPACE Subfunction Return Code and Reason Code 



The following table identifies the information returned in the LSPASFRT and 
LSPASFRS fields of the LSPACE macro's parameter list. 

N/A - Not Applicable 

CVSTAT - CVSTAT field of CVAF parameter list 

ENQ RETC - Return code from ENQ 

DIR RETC - Return code from CVAFDIR 

DSM RETC - Return code from CVAFDSM 

VRF RETC - Return code from CVAFVRF 

ECB STAT - ECB completion code 



2 Status information does not appear in the parameter list for return code 16. 
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LSPACE Inf onnation Return Areas 



The LSPACE macro returns status information to the parameter Ust and, 
optionally, the return of volume information to any of the three caller requested 
return areas described below. ^ 

Message Return Area: LSPACE returns information to a 30-byte message return 
area (Figure 10). If you provide a message return area with the MSG option, 
LSPACE returns EBCDIC text, qualified by return codes as shown in Figure 1 1 . 



LSPMSG DSECT Message Area 

LSPMTEXT DS CL30 Message Text 

Figure 10. DADSM LSPACE Free Space Information Format, MF=:(D,MSG) 



Return Text or 

Code Explanation 

16(X' 10') No text returned (invalid parameter list or SMF indicator) 

12(X'0C') Text: LSPACE— UCB NOT READY 
Text: LSPACE— UCBVTOC IS ZERO 
Text: LSPACE— INVALID PARAMETER 
Text: LSPACE— NOT A DIRECT ACCESS VOL 

08(X'08') Text: LSPACE— NON-STANDARD OS VOLUME 

04(X'04») Text: LSPACE— PERMANENT I/O ERROR 

OO(X'OO') Text: SPACE =aaaa,bbbb,cccc/dddd,eeee 

where: 

aaaa = Total number of free cylinders 

bbbb = Total number of additional free tracks 

cccc = Total number of free extents 

dddd = Number of cylinders in largest free extent 

eeee = Number of additional tracks in largest free extent 

Figure 11. DADSM LSPACE Message Area Contents 



Data Return Area: If you provide a data return area with the DATA option, 
LSPACE returns information as described in Figure 12. 



Requests for the MSG and DATA areas are mutually exclusive. LSPACE checks to 
ensure that the storage key of each information return area is equal to the caller's key 
or that the caller is authorized prior to its use. 
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Name 


Offset 


Bytes 


Description 


LSPDRETN 


OO(X'OO') 


1 


Return area status byte 


LSPDSPAC 




X'80' 


Returned space infonnation 


LSPDFOCN 




X'40' 


Returned format-0 DSCB count 


LSPDVRCN 




X'20' 


Returned free VIR count 


LSPDRRES 




...xxxxx 


Reserved 


LSPDSTAT 


Ol(X'Ol') 


1 


Status byte 


LSPDDCDS 




X'80' 


Index exists for VTOC 


LSPDDCAC 




X'40' 


Index VTOC active 


LSPDIRES 




..xxxxxx 


Reserved 


LSPDRSVl 


02(X'02') 


2 


Reserved 


LSPDNEXT 


04(X'04») 


4 


Number of free extents 


LSPDTCYL 


08(X'08') 


4 


Total free cylinders 


LSPDllRK 


12(X'0C') 


4 


Total additional free tracks 


LSPDLCYL 


16(X'10') 


4 


Number of cylinders in largest free extent 


LSPDLTRK 


20(X'14') 


4 


Number of additional tracks in largest free extent 


LSPDFOS 


24(X'18') 


4 


Format-0 DSCB count 


LSPDVmS 


28(X'1C') 


4 


Free VIR count 


LSPDFRAG 


32(X'20') 


4 


Fragmentation index^ 



Figure 12. Format of the LSPACE Data Return Area 
I Note to Figure 12: 



1 The fragmentation index is a numeric representation of the relative size and 
distribution of free space on the volume. A large index value indicates a high 
degree of fragmentation. 

Format 4 DSCB Return Area: If you provide a format-4 DSCB return area with the 
F4DSCB option, LSPACE returns information as described by the DSCB4 data 
area in Debugging Handbook. 



Example of LSPACE Using Message Return Area 



The following example requests that LSPACE return free space information in the 
message return area. 



LSPAMFIM LSPACE MSG=MYMSG, UCB= (R1 0) ,MF=I 



Example of LSPACE Using Data Return Area 



The following example requests that LSPACE return free space information in the 
data return area. 



LS PAMF I D LS PACE DATA=MYDATA , UCB= ( R 1 ) , MF= I 
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Example of LSPACE Specifying List and Execute Forms 



The following example uses the list form of the macro to define the parameter list, 
and the execute form to refer to the same parameter list 



LSPALIST LSPACE MSG=MYDATA,MF=L 



LSPAEX LSPACE MF= (E, LSPALIST) ,UCB= (R1 0) 



Reading a Control Block from the VTOC 



Reading a DSCB by Name (OBTAIN and CAMLST SEARCH) 



If you specify a data set name using OBTAIN and the CAMLST SEARCH option, 
the OBTAIN routine reads the 96-byte data portion of the identifier (format- 1) 
DSCB and the absolute track address of the DSCB into virtual storage. The 
absolute track address is a 5-byte field in the form CCHHR. The absolute track 
address field contains zeros for VSAM and VIO data sets. 

Because the VTOC does not contain a format- 1 DSCB for a suballocated VSAM 
data space, an OBTAIN request, which searches the VTOC for such a data space's 
DSCB, fails. If the volume contains VSAM data sets, the OBTAIN routine uses 
information from the VSAM catalog to build a pseudo format- 1 DSCB, setting its 
CCHHR to zeros. 

The format is: 



[symbol] 


OBTAIN 


listname-addrx 


listname 


CAMLST 


SEARCH 

,dsname-relexp 

^vol-relexp 

ywkarea-relexp 



listname-addrx 

points to the parameter list (labeled listname) set up by the CAMLST macro 
instruction. 

SEARCH 

this operand must be coded as shown. 

dsname-relexp 

specifies the virtual storage location of a fully qualified data set name. The 
area that contains the name must be 44 bytes long. 

Note: A DSNAME of 44 bytes of X'04' (X* 040404... 04') can be used to 
read a format-4 DSCB. 
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OBTAIN 


* 




* 




DSCBABC 


CAMLST 


DSABC 


DC 


VOLNUM 


DC 


WORKAREA 


DS 



vol-relexp 

specifies the virtual storage location of the 6-byte volume serial number on 
which the DSGB is located. 

wkarea-relexp 

specifies the virtual storage location of a 140-byte work area that you must 
define. 

Example: In the following example, the identifier (fonnat-1) DSCB for data set 
A.B.C is read into virtual storage using the SEARCH option. The serial number of 
the volume containing the DSCB is 770655. 



DSCBABC READ DSCB FOR DATA 

SET A.B.C INTO DATA 
AREA NAMED WORKAREA 

SEARCH , DSABC , VOLNUM , WORKAREA 

CL44' A.B.C DATA SET NAME 

CL6' 770655' VOLUME SERIAL NUMBER 

140C 140-BYTE WORK AREA 



Note: Check the return codes. 

The OBTAIN macro instruction points to the CAMLST macro instruction. 
SEARCH, the first operand of CAMLST, specifies that a DSCB be read into 
virtual storage, using the data set name you have supplied at the address indicated 
in the second operand. DSABC, the second operand, specifies the virtual storage 
location of a 44-byte area into which you have placed the fully qualified name of 
the data set whose format- 1 DSCB is to be read. VOLNUM, the third operand, 
specifies the virtual storage location of a 6-byte area into which you have placed 
the serial number of the volume containing the required DSCB. WORKAREA, the 
fourth operand, specifies the virtual storage location of a 140-byte work area into 
which the DSCB is to be returned. 

Control is returned to your program at the next executable instruction following the 
OBTAIN macro instruction. If the DSCB has been successfully read into your 
work area, register 15 contains zeros. Otherwise, register 15 contains one of the 
following return codes. The return codes are shown in decimal, with hexadecimal 
values in parentheses. 
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Return Codes from OBTAIN (Reading by data set name) 



Code Meaning 

4(X'04') The required volume was not mounted. 

8(X'08') The format-1 DSCB was not found in the VTOC of the 
specified volume. 

12(X'0C') A permanent I/O error was encountered, or an invalid 

format-1 DSCB was found when processing the specified 
volume, or an unexpected error return code was received 
from CVAF (Common VTOC Access Facility). 

16(X' 10') Invalid work area pointer. 



After execution of these macro instructions, the first 96 bytes of the work area 
contain the data portion of the identifier (format-1 or format-4) DSCB; the next 5 
bytes contain the absolute track address (CCHHR) of the DSCB. These 5 bytes 
contain zeros for VSAM or VIO data sets. 



Reading a DSCB by Absolute Device Address (OBTAIN and CAMLST SEEK) 



You can read any DSCB from a VTOC using OBTAIN and the CAMLST SEEK 
option. You specify the SEEK option by coding SEEK as the first operand of the 
CAMLST macro and by providing the absolute device address of the DSCB you 
want to read, unless the DSCB is for a VIO data set. Only the SEARCH option 
can be used to read the DSCB of a VIO data set. 

The format is: 



[symbol] 


OBTAIN 


listname-addrx 


listname 


CAMLST 


SEEK 

^cchhr-relexp 

yvol-relexp 

^wkarea-relexp 



listname-addrx 

points to the parameter list (labeled listname) set up by the CAMLST macro 
instruction. 

SEEK 

this operand must be coded as shown. 

cchhr-relexp 

specifies the virtual storage location of the 5-byte absolute device address 
(CCHHR) of a DSCB. 
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vol-relexp 

specifies the virtual storage location of the 6-byte volume serial number on 
which the DSCB is located. 

wkarea-relexp 

specifies the virtual storage location of a 140-b3rte work area that you must 
define. 

Example: In the following example, the DSCB at actual-device address 
X'OO 00 00 01 07' is returned in the virtual storage location READAREA, 
using the SEEK option. The DSCB resides on the volume with the volume serial 
number 108745. 





OBTAIN 


ACTADDR READ DSCB FROM 


* 




LOCATION SHOWN IN CCHHR 


* 




INTO STORAGE AT LOCATION 


* 




NAMED READAREA 


ACTADDR 


CAMLST 


SEEK , CCHHR , VOLSER , READAREA 


CCHHR 


DC 


XLS '0000000 107' ABSOLUTE TRACK ADDRESS 


VOLSER 


DC 


CL6' 108745' VOLUME SERIAL NUMBER 


READAREA 


DS 


140C 140-BYTE WORK AREA 



Note: Check the return codes. 

The OBTAIN macro points to the CAMLST macro. SEEK, the first operand of 
CAMLST, specifies that a DSCB be read into virtual storage. CCHHR, the second 
operand, specifies the storage location that contains the 5-byte actual-device 
address of the DSCB. VOLSER, the third operand, specifies the storage location 
that contains the serial number of the volume where the DSCB resides. The fourth 
operand, READAREA, specifies the storage location to which the 140-byte DSCB 
is to be returned. 

Control is returned to your program at the next executable instruction following the 
OBTAIN macro instruction. If the DSCB has been successfully read into your 
work area, register 15 contains zeros. Otherwise, register 15 contains one of the 
following return codes. The return codes are shown in decimal, with hexadecimal 
values in parentheses. 
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Return Codes from OBTAIN (Reading by Absolute Device Address) 



Code Meaning 

4(X'04') The required volume was not mounted. 

8 (X • 08 • ) The format- 1 DSCB was not found in the VTOC of the 
specified volume. 

1 2(X ' OC ) A permanent I/O error was encountered or an 

unexpected error return code was received from CVAF. 

1 6 (X ' 1 ' ) Invalid work area pointer. 

20(X' 14' ) The SEEK option was specified and the absolute track 

address (CCHHR) is not within the boundaries of the VTOC. 



Deleting a Data Set from the VTOC (SCRATCH and CAMLST SCRATCH) 

You can use the SCRATCH and CAMLST macro instructions to delete a 
non-VSAM data set. SCRATCH processing deletes the associated data set control 
blocks (DSCBs) and makes the space occupied by the data set available for 
reallocation. Be aware that this process may not erase the data from the disk. 
Data sets that contain sensitive data should be erased (overwritten with zeros) 
before their space is made available. This erase can either be done before issuing 
the SCRATCH macro, or be requested in scratch processing by 

• Providing an associated RACF ERASE attribute, or 

• Activating bit 21 (X* 00 00 04 00' ) of the SCRATCH parameter list. 

Authorized callers of SCRATCH may set bit 22 to ' 1 ' to override the RACF 
profile ERASE attribute. 

If you want to scratch a data set being processed using virtual input/output (VIO), 
the data set must have been allocated for use by your job. Scratching VIO data 
sets not allocated to your job is not allowed. 

If the data set to be deleted is sharing one or more cylinders with one or more data 
sets (a split-cylinder data set), the space will not be made available for reallocation 
until all data sets on the shared cylinders are deleted. 

A data set cannot be deleted if the expiration date in the identifier (format- 1) 
DSCB has not passed, unless you choose to ignore the expiration date. You may 
specify that DADSM is to ignore the expiration date by specifying the OVRD 
option in the CAMLST macro instruction. 

DADSM SCRATCH processing supports three never-scratch dates. To ensure that 
a data set will never be scratched, specify the expiration date as either of the 
following: 
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. 1999.365 
. 1999.366 
. 1999.999 

For information on RACF-defined data sets, see RACF General Information 
Manual. You may scratch a RACF-defined data set (that is, the DSCB indicates 
RACF-defined) only if you have alter access authority to either the data 
set/ volume serial in the DATASET class, or to the volume serial in the DASDVOL 
class (if the volume is RACF-defined). 

If a data set to be deleted is stored on more than one volume, either a device must 
be available for mounting the volumes or at least one volume must be mounted. In 
addition, all other required volumes must be serially mountable. 

When deleting a data set, you must build a volume list in virtual storage. This 
volume list consists of an entry for each volume on which the data set resides. The 
first two bytes of the list indicate the number of entries in the list. Each 12-byte 
entry consists of a 4-byte device code, a 6-byte volume serial nimiber, and a 2-byte 
scratch status code that should be initialized to zero. 

If the space to be deleted is a VSAM data space, you must use the DELETE 
command provided by access method services. For complete information about the 
DELETE command, see Access Method Services Reference. 

Volumes are processed in the order that they appear in the volume list. The 
volume at the beginning of the list is processed first. If a volume is not mounted, a 
message is issued to the operator requesting that a volume be mounted. (A volume 
mount message wUl not be issued for a mass storage system (MSS) virtual volume; 
however, a status code will be returned to your program.) This is only done if 
register has been loaded with the address of the UCB associated with the device 
where unmounted volumes are to be mounted. (The device must be allocated to 
your job.) If you do not load register with a UCB address, its contents must be 
zero, and at least one of the volumes in the volume list must be mounted before the 
SCRATCH macro instruction is issued. 

If the requested volimie cannot be mounted, the operator issues a reply indicating 
that the request cannot be fulfilled. A status code is then set in the last byte of the 
volume pointer (the second byte of the scratch status code) for the unavailable 
volume, and the next volume indicated in the volume list is processed. 

The format is: 



[symbol] 
listname 


SCRATCH 
CAMT,S1 


listname-addrx 
SCRATCH 
,dsname-relexp 
tyvol list-relexp 
[„OVRDl 



listname-addrx 

points to the parameter list (labeled listname) set up by the CAMLST macro 
instruction. 
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SCRATCH 

this operand must be coded as shown. 

dsname-relexp 

specifies the virtual storage location of a fully qualified data set name. The 
area that contains the name must be 44 bytes long. The name must be 
defined by a C-type Define Constant (DC) instruction. 

vol list-relexp 

specifies the virtual storage location of an area that contains a volimie list. 
The area must begin on a half word boundary. 

OVRD 

when coded as shown, specifies that the expiration date in the DSCB should 
be ignored. 

Example: In the following example, data set A.B.C is deleted from two volumes. 
The expiration date in the identifier (format- 1) DSCB is ignored. 





SR 


0,0 


SET REG TO ZERO 




SCRATCH 


DELABC 


DELETE DATA SET A.B.C 


* 






FROM TWO VOLUMES, 


* 






IGNORING EXPIRATION 


* 






DATE IN THE DSCB 


DELABC 


CAMLST 


SCRATCH, DSABC, 


, VOLIST,, OVRD 


DSABC 


DC 


CL44'A.B.C' 


DATA SET NAME 


VOLIST 


DC 


H'2' 


NUMBER OF VOLUMES 




DC 


X'3030200E' 


3380 DISK DEVICE CODE 




DC 


CL6'000017' 


VOLUME SERIAL NO. 




DC 


H'O' 


SCRATCH STATUS CODE 




DC 


X'3030200E' 


3380 DISK DEVICE CODE 




DC 


CL6' 000018' 


VOLUME SERIAL NO. 




DC 


H'O' 


SCRATCH STATUS CODE 



Note: Check the return codes and SCRATCH status codes. 

The SCRATCH macro instruction points to the CAMLST macro instruction. 
SCRATCH, the first operand of CAMLST, specifies that a data set be deleted. 
DSABC, the second operand, specifies the virtual storage location of a 44-byte 
area where you have placed the fully qualified name of the data set to be deleted. 
VOLIST, the fourth operand, specifies the virtual storage location of the volimie 
list you have built. OVRD, the sixth operand, specifies that the expiration date in 
the DSCB of the data set to be deleted be ignored. 

When you attempt to delete a password-protected data set that is not also 
RACF-protected, the operating system issues a message (IEC301A) to ask the 
operator at the console or the terminal operator of a remote console to enter the 
password. The data set will be scratched only if the password supplied is 
associated with a WRITE protection mode indicator. The protection mode 
indicator is described in Chapter 5, "Password Protecting Data Sets." 

Control is returned to your program at the next executable instruction following the 
SCRATCH macro instruction. If the data set has been successfully deleted, 
register 15 will contain zeros, and the scratch status code in the volume list entry 
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for each volume will be set to zero. Otherwise, register 15 will contain one of the 
return codes that follow. To determine whether the data set has been successfully 
deleted from each volume on which it resides, you must examine the scratch status 
code, that is, the last byte of each entry in the volume list. 



Return Codes from SCRATCH 



Code Meaning 

4(X'04') No volumes containing any part of the data set were mounted, nor 
did register contain the address of a unit that was available for 
mounting a volume of the data set. The data set may be a VIO data 
set that was not allocated during your job. (This return code is 
accompanied by a scratch status code of 5 in each entry of the 
volume list.) 

8(X' 08 ' ) An unusual condition was encountered on one or more volumes. 

12(X'0C') The volume list passed was invalid. The scratch status code (the last 
byte of each volume list entry) will not have been modified during 
scratch processing. 
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Status Codes from SCRATCH 



After the SCRATCH macro instruction is executed, the last byte of each 12-byte 
entry in the volume list indicates one of the following conditions in binary codes: 



Scratch 

Status 

Code Meaning 

All DSCBs for the data set have been deleted from the 
VTOC on the volume pointed to. 

1 The VTOC of this volume does not contain the format- 1 
DSCB for the data set to be deleted. 

2 The macro instruction failed when the correct password 
was not supplied in the two attempts allowed, or an 
attempt was made to scratch a VSAM data space or data set 
cataloged in an Integrated Catalog Facility catalog. 

3 The data set was not deleted from this volume because 
either the OVRD option was not specified or the 
retention cycle has not expired. 

4 A permanent I/O error was encountered, or an invalid 
format- 1 DSCB was found when processing this volume, 
or an unexpected error return code was received from 
CVAF. 

5 It could not be verified that this volume was mounted, 
and no device was available for mounting this volume. 

6 The operator was unable to mount this volume. 

For IBM Mass Storage Systems (MSS), a volume mount 
failure occurred. 

For a JES3-managed virtual volimie, JESS would not 
allow the volume to be mounted. 

7 The specified data set could not be scratched 
because it was being used. 

8 The DSCB indicates the data set is defined to RACF, 
but either the user is not authorized to access the 
data set or the volume, or the data set is a VSAM 

data space, or the data set is cataloged in an Integrated Catalog 
Facility catalog, or the data set is not defined to RACF. 
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Renaming a Data Set in the VTOC (RENAME and CAMLST RENAME) 

You rename a data set that is not cataloged in an Integrated Catalog Facility 
catalog or VSAM catalog by using the RENAME and CAMLST macro 
instructions. These cause the data set name in all format- 1 DSCBs for the data set 
to be replaced by the new name you supply. (VIO data sets cannot be renamed.) 

If a data set to be renamed is stored on more than one volume, either a device must 
be available for mounting the volumes, or at least one volume must be mounted. In 
addition, all other volumes of the data set must be serially mountable. 

For information on RACF-defined data sets, see RACF General Information 
Manual. Only a user with alter access authority may rename a RACF-defined data 
set. 

When renaming a data set, you must build a volume list in virtual storage. This 
volume list consists of an entry for each volume on which the data set resides. The 
first two bytes of the list indicate the number of entries in the list. Each 12-byte 
volume list entry consists of a 4-byte device code, a 6-byte volume serial number, 
and a 2-byte rename status code that should be initialized to zero. Volumes are 
processed in the order in which they appear in the volume list. The first volume on 
the list is processed first. If a volume is not mounted, a message is issued to the 
operator requesting that the volume be mounted. (A volume mount message will 
not be issued for an MSS volume; however, a status code is returned to your 
program.) This is only done if you indicate the direct access device on which 
unmounted volumes are to be mounted by loading register with the address of the 
UCB associated with the device to be used. (The device must be allocated to your 
job.) If you do not load register with a UCB address, its contents must be zero, 
and at least one of the volumes in the volume list must be mounted before the 
RENAME macro instruction is executed. 

If the operator cannot mount a volume in the volume list, a reply is issued that the 
request cannot be fulfilled. A status code is then set in the last byte of the volume 
list entry (the second byte of the rename status code) for the unavailable volume, 
and the next volume indicated in the volume list is processed or requested. 

The format is: 



[symbol\ 


RENAME 


listname-addrx 


listname 


CAMLST 


RENAME 

^dsname-relexp 
ynew name-relexp 
yvol list-relexp 



listname-addrx 

points to the parameter list (labeled listname) set up by the CAMLST macro 
instruction. 

RENAME 

this operand must be coded as shown. 
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dsname-relexp 

specifies the virtual storage location of a fully qualified data set name to be 
replaced. The area that contains the name must be 44 bytes long. The name 
must be defined by a C-type Define Constant (DC) instruction. 

new name-relexp 

specifies the virtual storage location of a fully qualified data set name that is 
to be used as the new name. The area that contains the name must be 44 
bytes long. The name must be defmed by a C-type Define Constant (DC) 
instruction. 

vol list-relexp 

specifies the virtual storage location of an aresa that contains a volume list. 
The area must begin on a halfword boundary. 

Example: In the following example, data set A.B.C is renamed D.E.F. The data 
set resides on two volumes. 





SR 


0,0 


SET REG TO ZERO 




RENAME 


DSABC 


CHANGE DATA SET 
NAME A.B.C TO D.E.F 


DSABC 


CAMLST 


RENAME, OLDNAME, 


, NEWNAME, VOLIST 


OLDNAME 


DC 


CL44'A.B.C' 


OLD DATA SET NAME 


NEWNAME 


DC 


CL44'D.E.F' 


NEW DATA SET NAME 


VOLIST 


DC 


H'2' 


TWO VOLUMES 




DC 


X'3030200E' 


3380 DISK DEVICE CODE 




DC 


CL6'000017' 


VOLUME SERIAL NO. 




DC 


H'O' 


RENAME STATUS CODE 




DC 


X'3030200E' 


3380 DISK DEVICE CODE 




DC 


CL6'000018' 


VOLUME SERIAL NO. 




DC 


H'O' 


RENAME STATUS CODE 



Note: Check the return codes and RENAME status codes. 

The RENAME macro instruction points to the CAMLST macro instruction. 
RENAME, the first operand of CAMLST, specifies that a data set be renamed. 
OLDNAME, the second operand, specifies the virtual storage location of a 44-byte 
area where you have placed the fully qualified name of the data set to be renamed. 
NEWNAME, the third operand, specifies the virtual storage location of a 44-byte 
area where you have placed the new name of the data set. VOLIST, the fourth 
operand, specifies the virtual storage location of the volume list you have built. 

Control is returned to your program at the next executable instruction following the 
RENAME macro instruction. If the data set has been successfully renamed, 
register IS will contain zeros, and the rename status code in the volume list entry 
for each volume will be set to zero. Otherwise, register 15 will contain one of the 
return codes below. To determine whether the data set has been successfully 
renamed on each volume where it resides, you must examine the rename status 
code, the last byte of each entry in the volume Ust. 
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Return Codes from RENAME 



Code Meaning 

4(X'04') No volumes containing any part of the data set were 

mounted, nor did register contain the address of a unit 
that was available for mounting a volume of the data set 
to be renamed. 

The data set may be a VIO data set and cannot be renamed. 
(TTiis return code is accompanied by a rename status code 
of 5 in each entry of the volume list.) 

8(X'08') An unusual condition was encountered on one or more 
volumes. 

12(X'0C') The volume list passed was invalid. 

The rename status code, the last byte of each volume list 
entry, will not have been modified during rename 
processing. 



After the RENAME macro instruction is executed, the last byte of each 12-byte 
entry in the volume list indicates one of the following conditions in binary code: 
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Rename 

Status 

Code Meaning 

The format- 1 DSCB for the data set has been renamed in 
the VTOC on the volume pointed to. 

1 The VTOC of this volume does not contain the format- 1 
DSCB for the data set to be renamed. 

2 The macro instruction failed when the correct password 
was not supplied in the two attempts allowed, or the 
user tried to rename a VSAM data space or VSAM data 
set cataloged in an Integrated Catalog Facility catalog. 

3 A data set with the new name already exists on this 
volume. 

4 A permanent I/O error was encountered, or an invalid 
format- 1 DSCB was found when trying to rename the data 
set on this volume, or an unexpected error return code 
was received from CVAF. 

5 It could not be verified that the volume was mounted, 
and no device was available for mounting the volume. 

6 The operator was unable to mount this volume. 
For Mass Storage Systems (MSS), a volume mount 
failure occurred. 

For a JES3-managed virtual volume, JES3 would not 
allow the volume to be mounted. 

7 The specified data set could not be renamed on 
this volume because it was being used. 

8 The data set is defined to RACF, but either the 
user is not authorized to alter the data set 

or the data set is defined to RACF on multiple 
volumes. 



When you attempt to rename a password-protected data set, the operating system 
issues a message (IEC301 A) to ask the operator or remote console operator to 
verify the password. The data set will be renamed only if the password supplied is 
associated with a WRITE protection mode indicator. The protection mode 
indicator is described in Chapter 4, "Password Protecting Data Sets" on 
page 111. 
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Accessing the VTOC and its Index with CVAF Macros 



You may use CVAF or DADSM to access the VTOC or its index. DADSM access 
is described in "Accessing the VTOC with DADSM Macros" on page 19. 

CVAF macros and associated tasks include: 



CVAFDIR 
CVAFDSM 
CVAFFILT 
CVAFSEQ 



CVAFTST 



- Directly access DSCBs or VTOC index records. 

- Obtain volume free space information. 

- Read sets of DSCBs for one or more DASD data sets. 

- Retrieval of the following: 

- Data set names from an active VTOC index. 

- DSCBs in physical-sequential order. 

- DSCBs in data set name order (index required) . 

- Determine if a DASD volume has an active VTOC index, 



Serialization and Updating 



Identifying the Volume 



Appendix A, "CVAF VTOC Access Macros" on page 231, contains detailed 
descriptions of these macros. Appendix B, "Examples of VTOC Access Macros" 
on page 259, contains examples of their use. 



CVAF requires that you provide all necessary system resource serialization for 
your request. You can only ensure the integrity of multiple data elements (sets of 
DSCBs and/or VIRs) returned by CVAF if you serialize system resources 
adequately. You compound this exposure if you must make multiple CVAFFILT 
requests for a desired set of DSCBs and/or VIRs. 

You must weigh possible system performance loss because of serialization against 
the potential loss of data integrity. If you make updates without adequate 
serialization, you may compromise the integrity of the volume's VTOC, the VTOC 
index, and/or any associated data set. 

CVAF only honors requests to modify the volume's VTOC and/or index from 
authorized programs. 

CVAF assumes that an authorized program holds an exclusive RESERVE (or 
ENQ) on the qname (major name) of SYSVTOC, mame (minor name) of the 
volume's serial number, with the scope of SYSTEMS. The SYSVTOC qname does 
not serialize access to the format- 1 DSCB for a data set. You may provide this 
serialization by allocating the data set with disposition OLD, MOD, or NEW (not 
SHR). This causes the proper ENQ, ensuring that no other job can update that 
data set's format- 1 DSCB. 



If you are authorized, you may identify the volume to the CVAFDIR, CVAFDSM, 
CVAFFILT, and CVAFSEQ macros by specifying the address of its UCB. If you 
are not authorized, you must identify the volume by specifying the address of a 
SAM or EXCP DEB opened to the volume's VTOC. 

The DEB can be obtained by opening a DCB using the RDJFCB and OPEN 
TYPE=J macros. The DCBs DDNAME is that of a DD statement allocated to the 
unit whose VTOC is to be accessed. After issuing the RDJFCB macro, the 
JFCBDSNM field is overlaid with the data set name of the format-4 DSCB: 
44X'04'. You open the DCB for INPUT by using OPEN TYPE= J. The DEB 
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Using Registers 



address is in DCB field DCBDEBA. The OPEN macro is described under 
"OPEN — Initialize Data Control Block for Processing the JFCB" on page 148; 
the RDJFCB macro is described under "RDJFCB — Read a Job File Control 
Block" on page 137. 

If a CVAF macro call specifies IOAREA=KEEP, a subsequent CVAF call using a 
different CVPL may omit the UCB and DEB keywords and supply the lOAREA 
address from the other CVPL. You can use the lOAREA keyword to do this. 

The requirements cited above do not apply to the CVAFTST macro. The 
CVAFTST macro only allows you to identify the VTOC by specifying a UCB, and 
does not require that you be authorized. 



Register 1 contains the address of the CVAF parameter list (CVPL). Register 15 
contains the return code when processing for a function is complete. 



Generating a CVPL (CVAF Parameter List) 



All the CVAF macros except CVAFTST use the CVPL to pass parameters to 
CVAF. The CVAFTST macro expands to provide its only parameter (UCB 
address) in register 1, and calls the associated CVAF module. CVAF uses the 
CVPL to return information related to the CVAF request. 

CVAF generates a CVPL when you specify the CVAFDIR, CVAFDSM, 
CVAFFILT, or CVAFSEQ macro with MF=L or MF=I as a subparameter. If 
you do not specify the MF subparameter, MF=I is the default. Upon return, the 
CVIIVT bit indicates whether an indexed or nonindexed VTOC was accessed. 
The CVSTAT field contains feedback when an error occurs. The address of the 
map records buffer list is returned in the CVMRCDS field. The address of the 
VIER buffer list is returned in the CVIRCDS field. CVAF returns the CVAF I/O 
area address in the CVIOAR field. CVAF returns the CVAF Filter Save Area 
address in the CVFSA field. 

You may use the CVPL generated by the MF=L or MF=I form of the CVAFDIR, 
CVAFDSM, CVAFFILT, or CVAFSEQ macros (by using the MF=E keyword) to 
execute a different function than that specified by the macro that originally 
generated the CVPL. If you specify a CVAF filter request, you must use a CVPL 
generated by the CVAFFILT macro. (To support the CVFSA field, the 
CVAFFILT macro generates a CVPL four bytes larger than that generated by the 
other CVAF macros.) 

The ICVAFPL macro maps the CVPL. The format of the CVPL is shown in 
Figure 13 on page 44. 
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Name 



Offset 



Bytes 



Description 



CVPL 






CVLBL 


OO(X'OO') 


4 


CVLTH 


04(X'04') 


2 


CVFCTN 


06(X'06') 


1 


CVSTAT 


07(X'07') 


1 


CVFLl 


08(X'08') 


1 


CVirvT 




X»80' 


CVIIOAR 




X'40' 


CVIPGM 




X'20' 


CVIMRCDS 




X'lO' 


CVIIRCDS 




X'08' 


CVIMAPIX 




X^04' 


CVIMAPVT 




X'02' 


CVIMAPVL 




X'Ol' 


CVFL2 


09(X'09') 


1 


CV2HIVIE 




X'80' 


CV2VRF 




X'40' 


CV2CNT 




X'20' 


CV2RCVR 




X'lO' 


CV2SRCH 




X'08' 


CV2DSNLY 




X'04' 


CV2VER 




X'02' 


CV2NLEVL 




X'Ol' 


CVFL3 


10(X»0A') 


1 


CV3FILT 




X'80' 


CV3IXERR 




X'40' 
..xxxxxx 




ll(X'OB') 


1 


CVUCB 


12(X'0C') 


4 


CVDSN 


16(X'10') 


4 


CVFCL 


16(X'10') 


4 


CVBUFL 


20(X'14') 


4 


CVIRCDS 


24(X'18') 


4 


CVMRCDS 


28(X'1C') 


4 


CVIOAR 


32(X'20') 


4 


CVDEB 


36(X'24') 


4 


CVARG 


40(X'28') 


4 


CVSPACE 


44(X'2C') 


4 


CVEXTS 


48(X'30') 


4 


CVBUFL2 


52(X'34») 


4 


CVVRFDA 


56(X'38') 


4 


CVCTAR 


60(X»3C') 


4 


CVFSA 


64(X'40') 


4 



EBCDIC 'CVPL' 

Length of CVPL 

64(X'40') for macros other than CVAFFILT 

68(X'44') for CVAFFILT macro 

Function byte (See Figure 14 on page 45) 

Status information 

First flag byte 

Indexed VTOC accessed 



IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

Second flag byte 

HIVIER=YES 

VRF data exists 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

New highest level VIER (output) 

Third flag byte 

FLTAREA=KEEP 

Index error found 

Reserved 

Reserved 

UCB address 

Data set name address 

Filter criteria list address 

Buffer list address 

Index VIRs buffer list address 

Map VIRs buffer list address 

I/O area address 

DEB address 

Argument address 

SPACE parameter list address 

Extent table address 

New VRF VIXM buffer list address 

VRF data address 

Count area address 

Filter save area 



Figure 13. Format of the CVAF Parameter List (CVPL) 



Note: The CVAFFILT macro generates a CVPL four bytes longer (total length 
X'44') than that generated by the other CVAF macros (total length ~ X'40'). 
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The possible contents of the CVFCTN field in the CVPL and their meanings are as 
follows: 



Buffer Lists 



Name 


Description 




CVDIRD 


x'or 


-CVAFDIR 


ACCESS=READ 


CVDIWR 


X'02' 


-CVAFDIR 


ACCESS=WRITE 


CVDIRLS 


X'03' 


-CVAFDIR 


ACCESS=RLSE 


CVSEQGT 


X'04' 


-CVAFSEQ 


ACCESS=GT 


CVSEQGTE 


X'05' 


-CVAFSEQ 


ACCESS^GIHQ 


CVDMIXA 


X'06' 


-CVAFDSM 


ACCESS=DCADD 


CVDMIXD 


X'07' 


-CVAFDSM 


ACCESS=DCDLT 


CVDMALC 


X'08' 


-CVAFDSM 


ACCESS=ALLOC 


CVDMRLS 


X'09' 


-CVAFDSM 


ACCESS=RLSE 


CVDMMAP 


X'OA 


' -CVAFDSM 


ACCESS=MAPDATA 


CWOL 


X'OB 


-CVAFVOL 


ACCESS=VIBBLD 


CWRFRD 


X'OC 


• -CVAFVRF 


ACCESS=READ 


CWRFWR 


X'OD 


' -CVAFVRF 


ACCESS=WRirH 


CVFIRD 


X'OE 


• -CVAFFILT 


ACCESS=READ 


CVFIRES 


X'OF 


-CVAFFILT 


ACCESS=RESUME 


CVFIRLS 


X'lO' 


-CVAFFILT 


ACCESS=RLSE 



Figure 14. CVFCTN Field of CVPL— Contents and Defiiiitioiis 



A buffer list consists of one or more chained control blocks, each with a header and 
buffer list entries, obtained and initialized by your program before calling CVAF. 
The header indicates whether the buffer list is for DSCBs or VTOC index records. 
The entries point to and describe the buffers. 

You can create buffer lists in two ways: 

• Directly, when you fill in the arguments and buffer addresses of DSCBs or 
VlRs to be read or written 

• Indirectly (by CVAF), when you code the IXRCDS=KEEP and/or 
MAPRCDS=YES keywords 

The ICVAFBFL macro maps CVAF buffer lists. Figure IS on page 46 shows the 
format of a buffer list header. Figure 16 on page 47 shows the format of a buffer 
list entry. 

Buff or List Header: The buffer list header indicates whether the buffer list 
describes buffers for DSCBs or for VTOC index records. The DSCB bit must be 
set to one and the VIR bit to zero for CVAF to process a request to read or write a 
DSCB. CVAF requires that you provide buffer lists and buffers in your program's 
protect key. CVAF uses the protect key and subpool fields in the buffer list header 
only if you code ACCESS=RLSE. 
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Each buffer list header contains a count of the number of entries in the buffer list 
that directly follows the header. 

The forward chain address chains buffer lists together. You must not chain DSCB 
buffer lists to VIR buffer lists, or VIR buffer lists to DSCB buffer lists. 

The format of the buffer list header is shown in Figure 15. 



Name 



Offset 



Bytes 



Description 



BFLHDR 

BFLHNOE 

BFLHFL 

BFLHKEY 

BFLHVIR 

BFLHDSCB 


O(X'OO') 
0(X'00») 
l(X'Ol') 


8 
1 
1 

XXXX ... 

X'08' 
X'04' 


BFLHSP 
BFLHFCHN 


2(X'02') 
3(X'03') 
4(X'04') 


XX 

1 
1 

4 



Buffer list header 

Number of entries 

Flag byte and key 

Protect key of buffer list and buffers 

Buffer list entries describe VTRs 

Buffer Ust entries describe DSCBs 

Reserved 

Reserved 

Identifies the subpool of buffer list and buffers 

Forward chain address of next buffer list 



Figure 15. Format of a Buff er List Header 



Buffer List Entry: A buffer list contains one or more entries. Each entry provides 
the buffer address, the length of the DSCB or VTR buffer, the argument, and an 
indication whether the argument is an RBA, a TTR, or a CCHHR. 

The fields and bit uses are listed below. 

• For a VIR buffer, the TTR and CCHHR bits must be 0, and the RBA bit must 
be 1. 

. For a DSCB buffer, the RBA bit must be 0, and one of either the TTR or 
CCHHR bits must be set to 1 (they must not both be 1). 

• The BFLEAUPD bit is an output indicator from CVAF that the BFLEARG 
field of a VIR buffer list was updated. 

• The BFLEMOD bit indicates that a VIR buffer was modified and must be 
written; if no BFLEMOD bits are on in any of the entries for a CVAFDIR 
ACCESS=WRITE, all buffers are written. 

• The BFLESKIP bit is used to cause an entry to be ignored, 

• The BFLEIOER bit is an output indicator from CVAF to indicate an I/O error 
occurred during reading or writing of the DSCB or VIR. 

• The BFLELTH field is the length of the buffer; for a DSCB buffer, the length 
must be 96 or 140; for a VIR buffer, the length must be the length of the 
buffer divided by 256. 

• The BFLEARG field is the argument of the DSCB or VIR. Specify the desired 
format of the 5-byte field by setting either the BFLECHR, BFLETTR, or 
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BFLERBA bit to 1. The respective BFLEARG values and formats are as 
follows: 

- CCHHR=5 byte CCHHR 

- TTR=OTTRO 

- RBA=One byte of followed by a 4-byte RBA 

The optional and required values for BFLEARG are dependent upon the variables 
associated with a given request. These are described in the following 
request-oriented topics. 

The format of the buffer list entry is shown in Figure 16. 



Name 


Offset 


Bytes 


Description 


BFLE 


O(X'OO') 


12 


Buffer list entry 


BFLEFL 


O(X'OO') 


1 


Flag byte 


BFLERBA 




X«80' 


Argument is RBA 


BFLECHR 




X'40« 


Argument is CCHHR 


BFLETTR 




X'20' 


Argument is I'lK 


BFLEAUPD 




X'lO' 


CVAF updated argument field 


BFLEMOD 




X'08' 


Data in buffer has been modified 


BFLESKIP 




X'04« 


Skip this entry 


BFLEIOER 




X'02' 


I/O error 






X 


Reserved 




l(X'Ol') 


1 


Reserved 


BFLELTH 


2(X'02') 


1 


Length of VIR buffer divided by 256, or length of DSCB 
buffer 


BFLEARG 


3(X'03') 


5 


Argument of VIR or DSCB 


BFLEATTR 


4(X'04') 


3 


l"i R of DSCB 


BFLEARBA 


4(X'04') 


4 


RBA of VIR 


BFLEBUF 


8(X'08') 


4 


Buffer address 



Figure 16. Format of a Buff er List Entry 



Accessing the DSCB Directly 



You may use the CVAFDIR macro to read or write a DSCB. You may also use it 
to read or write VTOC index records for indexed VTOCs. "CVAFDIR Macro" on 
page 23 1 discusses detailed information about the CVAFDIR VTOC access 
macro. 

After a CVAFDIR call, you may test the CVAF parameter list bit, CVIIVT, to 
determine whether the VTOC is indexed or nonindexed. 
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specif ^ng a Data Set Name to Read or Write a DSCB: If you want to read or write 
a single DSCB by specifying only the data set name (that is, BFLEARG is zero) 
you must specify either ACCESS=READ or ACCESS=WRITE. 

Specify the address of the data set name in the DSN keyword. Specify the address 
of the buffer list in the BUFLIST keyword. Each of these areas and the associated 
buffers must be in your program's protect key. 

The buffer list must contain at least one buffer list entry with the skip bit off and a 
pointer to a 96-byte buffer. You must not provide 140-byte buffers. You may 
chain buffer lists together, but CVAF only uses the first eligible entry. 

For an indexed VTOC, CVAF searches the index for the data set name and, if it is 
found, puts the DSCB argument into the buffer list entry and uses it to read or 
write the DSCB. If CVAF cannot find the data set name in the index, CVAF does 
a key search of the VTOC. 

For a nonindexed VTOC, CVAF uses a channel program to do a key search of the 
VTOC to locate the data set name and read or write the DSCBs. If CVAF finds 
the data set name, CVAF puts the DSCB argument into the buffer list entry. 

The DSCB argument returned in the buffer list entry is in the format determined by 
the buffer list entry bits BFLECHR or BFLETTR. 

If CVAF does not find the data set name in the VTOC, it provides a return code of 
'4' in register 15, and an error code of ' 1 ' in the CVSTAT field. 

Specifying the DSCB Loaition: If you want to read or write a DSCB by specifying 
the DSCB's location (that is, BFLEARG), you must specify either 
ACCESS=READ or ACCESS=WRITE. 

Specify the address of the data set name in the DSN keyword. Specify the address 
of the buffer list in the BUFLIST keyword. Each of these areas and the associated 
buffer(s) must be in your program's protect key. 

The buffer list must have at least one buffer list entry with the skip bit off and a 
pointer to a 96-byte or 140-byte buffer. You may chain buffer lists together, but 
CVAF only uses the first eligible entry. 

If the buffer is for a 96-byte read or write, CVAF issues a channel program to 
verify that the key in the DSCB is the same as the 44-byte data set name you 
provide. CVAF does not execute the read or write unless the keys match. If they 
do not match, CVAF ignores the specified BFLEARG and reads or writes the 
DSCB according to the rules given in "Specifying a Data Set Name to Read or 
Write a DSCB" on page 48. 

If the buffer is for a 140-b)rte read or write, CVAF issues a channel program to 
read or write the DSCB at the location specified in the buffer list entry. CVAF 
does not use the data set name you specified. If you specify VERIFY=YES, 
CVAF verifies that the designated DSCB is a format-0 DSCB before issuing the 
write channel program. 
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Reading or Writing VTOC Index Records: You may read or write VIRs explicitly by 
using the BUFLIST keyword. You may read them implicitly by using the IXRCDS 
and MAPRCDS keywords. You may supply a buffer list address in the BUFLIST 
keyword to read or write one or more VIRS. The buffer list header must have the 
VIR bit set to one and the DSCB bit set to zero. CVAF inspects each entry in the 
buffer list (and any chained extensions). If the skip bit is set to zero, the RBA bit 
is set to one (and the CCHHR and TTR bits are set to zero), and the buffer 
address is nonzero, CVAF processes the entry. CVAF uses the RBA in the 
argument field of the buffer list entry to read or write a VIR using the buffer 
address. CVAF processes read and write requests in the order of their appearance 
in the buffer Ust. 

Each of the storage areas you provide must be in your program's protect key. 

For a write request, CVAF inspects the modification bit in the buffer list entries. If 
the bit is not set to ' 1 ' in any entry, CVAF writes all the entries. CVAF sets the 
modification bit to zero for entries whose VIR is written. 

If you specify the keywords MAPRCDS=YES and/or IXRCDS=KEEP and, at 
the same time, you do not provide an address in the CVMRCDS/CVTRCDS fields 
of the CVPL, CVAF reads the map records and the first high-level VTOC index 
entry record. 

Reading Map Records and VIERS: If you want to read the VTOC index map 
records and first high-level VIER, and retain them in virtual storage, you must code 
either ACCESS=READ or ACCESS=WRITE. CVAF does not require either the 
DSN or BUFLIST fields. 

If you want to read and retain map records, you must code MAPRCDS = YES. The 
CVAF parameter list field CVMRCDS must be zero. CVAF obtains a buffer list 
with the number of entries and buffers required to read all the map VIRs. CVAF 
puts the buffer list address into the CVMRCDS field. 

If you want to read and retain the first high-level VIER and (if this requires an 
index search) aU VIERs read, you must code IXRCDS=KEEP. If the CVAF 
parameter list field CVIRCDS is zero, CVAF obtains a buffer list with entries and 
buffers, and reads the first high-level VIER. CVAF determines the number of 
entries and buffers. If CVIRCDS is not zero, CVAF reads only the VIERs 
required for an index search. 

You can only ensure the integrity of the maps and VIER that CVAF reads if you 
enqueue the VTOC and (for shared DASD) issue a reserve to the unit. 

You must release the map and VIER buffers acquired and retained by CVAF by 
issuing a subsequent CVAF call. 

Releasing Buffers and Buffer Lists Obtained by CVAF: You may release buffers and 
buffer lists acquired by CVAF in the three following ways: 

• To free the MAP records buffer list, code MAPRCDS=NO or 
MAPRCDS=(NO,addr) specifying any ACCESS. 

• To free the index records buffer list, code IXRCDS=NOKEEP or 
IXRCDS=(NOKEEP,addr) specifying any ACCESS. 
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• Issue a CVAF call with ACCESS=sRLSE, and specify a buffer list address with 
the BUFLIST keyword. 

CVAF frees all eligible buffers and any buffer lists if they become empty. Eligible 
buffers are those pointed to by buffer list entries with the skip bit off. CVAF frees 
a buffer list if none of its buffer list entries have the skip bit on. If buffer lists are 
chained together, CVAF checks and frees all buffer lists if appropriate. 

Ensure that you do not request CVAF to release the same buffer list twice by 
specifying its address in more than one place. 

Accessing DSNs or DSCBs in Sequential Order 

Each CVAFSEQ call may request the return of one of the following: 

• One format- 1 or format-4 DSCB in indexed (data-set-name) order. 

• One or more DSCBs in physical-sequential order (if you are unauthorized, you 
can only request one DSCB). 

• The next data set name in the index. 

CVAF reads the DSCBs into buffers supplied with the BUFLIST keyword. 
"CVAFSEQ Macro" on page 251 discusses detailed information about the 
CVAFSEQ VTOC access macro. 

Use the buffer list to specify the argument of each DSCB to be read. For indexed 
access, you must request 96-byte DSCBs in the buffer list. For physical-sequential 
access, you must request 140-byte DSCBs. 

If you select indexed order, CVAF returns each format- 1 or format-4 DSCB whose 
name is in the index. If you want CVAF to return only the data set names in the 
index (not the DSCBs), specify DSNONLY=YES. In this case, CVAF returns the 
CCHHR of the DSCB in the argument area supplied through the ARG keyword. 
CVAF updates the DSN area you specify, with the data set name of each DSCB 
read, each time you issue CVAFSEQ. 

Initiating Indexed Access (DSN Onkr): To initiate indexed access (DSN order), 
either supply in the area coded through the DSN kejrword 44 bytes of binary zeros 
(to indicate the first data set name in the index) or supply the data set name you 
want to serve as the starting place for the index search. 

The name that CVAF returns in the DSN area is the one equal to or greater than 
the DSN supplied, depending on the specification of the ACCESS keyword. 
CVAF updates the DSN field. 

The ACCESS keyword determines whether the search is for a DSN greater than or 
equal to that which you specify. 

If you specify DSNONLY=NO, CVAF returns the DSCB and argument to you, 
using the buffer list you provide with the BUFLIST keyword. CVAF uses the first 
entry in the buffer list with the skip bit set to '0' and a nonzero buffer address. 
You must specify the argument value if you set either the TTR or CCHHR bit in 
the buffer list entry to ' 1 '. The default is CCHHR. For indexed access, the DSCB 
size in the buffer list entry must be 96 bytes. 
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If you specify DSNONLY= YES, you must specify the CCHHR argument in the 
ARG area. 

Note that the data set name of the format-4 DSCB is in the index and that CVAF 
may return its name (44 bytes of X'04'). The format-4 DSCB's name is likely to 
be the first data set name in the VTOC index. 

Initiating Physical-Sequential Access: To initiate physical-sequential access, you 
must either specify DSN=0, or not specify the DSN parameter at all. To begin the 
read, you must initialize the argument field in the first buffer list entry to zero or to 
the argument of the DSCB. If the argument is zero, CVAF uses the argument of 
the start of the VTOC. 

You must set the DSCB size to 140 in buffer list entries. 

The ACCESS = specification determines whether CVAF reads the DSCB whose 
argument is supplied or the DSCB following it. 

For example, to read the first DSCB (the format-4 DSCB) in the VTOC, you may 
set the BFLEARG in the first buffer list entry to zero and specify 
ACCESS=GTEQ in the CVAFSEQ macro. If you subsequently specify 
ACCESS=GT, CVAF reads the second DSCB (the fkst format-5 DSCB). 

If you are authorized, CVAF reads as many DSCBs as there are entries in the 
buffer list, with a single CVAF call. If you are not authorized, CVAF only reads 
one DSCB. 

CVAF only uses one buffer list. CVAF does not inspect a second buffer list 
chained from the first. If you are authorized, CVAF uses all entries in the buffer 
list. CVAF does not inspect the skip bit. Each entry must have a buffer address, 
the length field set to 140, and the TTR or CCHHR bit set to 1 (if neither bit is 
set, CVAF sets the CCHHR bit on). If you are unauthorized, CVAF only uses the 
first entry. CVAF updates the argument field of each buffer list entry with the 
argument of the DSCB. The argument value is returned in either TTR or CCHHR 
format, depending on whether you set the TTR or CCHHR bit to 1 in the buffer 
list entry. The default is CCHHR. 

CVAF uses only the argument in the first entry to begin the search. CVAF does 
not inspect arguments in subsequent entries. If you specify a nonzero argument 
value in the first entry, a DSCB with that argument must exist. 

CVAF indicates an end-of-data condition by providing return code 4 in register 15, 
and a value of X' 20' in the CVSTAT field. CVAF sets the argument fields of all 
buffer list entries following the last DSCB read, to zero (the first entry is zero if 
CVAF does not read any DSCBs). 

Note that CVAF reads all DSCBs, including format-0 DSCBs. You cannot be 
certain that you have read aU format- 1 through fonnat-6 DSCBs until CVAF had 
read the entire VTOC. For a nonindexed VTOC, the format-4 DSCB field 
DS4HPCHR contains the CCHHR of the last format- 1 DSCB. Format-2 through 
format-6 DSCBs may reside beyond that location. For an indexed VTOC, the 
VMDS contains information about which DSCBs are format-0 DSCBs. 
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Reading Sets of DSCBs with CVAF Filter 



The CVAF filter service retrieves sets of DSCBs into buffers provided by the 
calling program. The following text summarizes this service and its requirements. 

• You may invoke the CVAF filter service by issuing the CVAFFBLT macro. 
"CVAFFILT Macro" on page 245 describes the macro's syntax and 
parameters. 

• You request DSCBs by specifying either one or more fully qualified data set 
names, or one partially qualified name. See "Filter Criteria List" on page 53 
and "Examples of Partially Qualified Names for CVAFFILT" on page 250 for 
further information. 

• For each of the qualifying data sets, CVAF Filter returns DSCBs in the order 
that they are chained in the VTOC: format 1, format 2, then format 3. CVAF 
does not return DSCBs of other formats. 

• CVAF filter service returns complete DSCB chains for one or more qualifying 
data sets into caller-provided buffers. See "Example of CVAFFILT Macro 
Sequences" on page 57 and "Example 3: Using the CVAFFILT Macro" on 
page 271 for further information. CVAF filter service does not return a 
partial DSCB chain: 

- If you do not provide enough buffers to hold all of the requested DSCBs, 
CVAF filter service returns one or more complete DSCB chains and/or a 
status code (CVSTAT in the CVPL). The status code indicates whether 
or not you may use a "RESUME" CVAF call to retrieve the rest (or more) 
of the requested DSCBs. See "RESUME Capability" for specific 
information. 

— If the total number of buffers provided is not sufficient to contain a data 
set's complete DSCB chain, CVAF filter service sets a status byte 
(FCLDSNST in the FCL), ignores the data set, and processes the next 
qualifying data set. You can avoid this situation by providing a minimum 
of eleven DSCB buffers (enough for a data set at the 123 extent limit). 

• You must identify a single DASD volume in the CVAF parameter list (CVPL). 
CVAF filter service supports both indexed and nonindexed VTOCs. 

• When calling CVAF, your program can be in either 24-bit or 31 -bit addressing 
mode. If it is in 31 -bit mode, the control blocks shown in Figure 17 on 

page 53 may reside above the 16Mb line. AH these areas must be accessible in 
your program's storage key. 

RESUME Capability: If CVAF filter service terminates before returning a data 
set's DSCBs because you did not provide enough buffers, CVAF filter service 
saves the information necessary for a RESUME function in the filter save area 
(You must specify FLTAREA=KEEP on the initial CVAFFILT call to cause 
CVAF filter service to obtain and keep the filter save area). 

To allow RESUME processing to execute correctly, you mus/ maintain the 
relationship between the requested volume (identified by CVDEB, C VUCB, or a 
kept 10 ARE A), your FCL, and CVAF's FSA. If you observe this requirement, 
you can initiate and resume multiple CVAF filter service operations 
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asynchronously on one or more DASD volumes. You can ensure this relationship 
by providing a unique CVPL and FCL for the duration of the 
READ/RESUME/RELEASE sequence associated with each logical request. 

If you issue an ACCESS=RESUME without having previously specified 
FLTAREA=KEEP, CVAF filter service provides return code •4' in register 15 
and '66' in the CVSTAT field. 

If you specify FLTAREA=KEEP, you must issue a subsequent CVAFFILT call 
with the ACCESS=RLSE keyword to release the filter save area storage. 
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DSN 
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Figure 17. Control Blocks Required for CVAF Filter Services 



FOter Criteria List 



The filter criteria list consists of two kinds of elements; a list header, and a variable 
number of list entries. The list entries immediately follow the header, and each 
entry represents a different data set name to be processed by CVAF filter. The 
header and entries, shown in Figure 18 and Figure 19 are mapped by the 
ICVFCL macro. The format of the FCL header is shown in Figure 18. 
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Name 



Offset 



Bytes 



Description 



FCLID 

FCLCOUNT 

FCLDSCBR 

FCLIFLAG 

FCLILIST 

FCLIORDR 

FCL2FLAG 

FCL2SEQ 

FCL2SDIR 



FCLDRSV lO(X'OA') 



OO(X'OO') 
04(X'04') 
06(X'06') 
08(X'08') 



09(X'09') 



4 

2 

2 

1 

X'80' 

X'40' 

..xxxxxx 

1 

X'80' 
X'40' 

..xxxxxx 



EBCDIC 'FCL • 

Number of data set name entries provided in the list. 

Number of DSCBs returned 

Request flag b3rte 

List contains fully qualified data set names 

FCL data set name order requested 

Reserved 

Status flag byte 

CVAFFILT executed sequential VTOC access 

CVAFFILT executed sequential VTOC access, but did at least 

one direct DSCB read 

Reserved 

Reserved 



Figure 18. Fonnat of a Filter Criteria List (FCL) Header 



FCLID 

Must be a 4-character EBCDIC constant of 'FCL ' . 

FCLCOUNT 

Specifies the number of data set name entries (FCLDSN) supplied in the list. 
You must not change this parameter between the initial CVAFFILT call and 
any subsequent RESUME operations. 

• When you specify a partially-qualified data set name, you must specify 
FCLCOUNT = L See "Examples of Partially Qualified Names for 
CVAFFILT" on page 250 for the format of partially qualified data set 
names. 

• When you specify a list of fully qualified names, CVAFFILT processes 
only the number of names specified in FCLCOUNT. 

FCLDSCBR 

Indicates the total number of DSCB entries (including format- 1, format-2, 
and format-3) retiuned to the caller's buffers by a single CVAFFILT call. 

Because CVAF may encounter an error after successfully processing a data 
set, you may: 

1 . Initialize FCLDSCBR to before each READ and RESUME call. 

2. Upon return from CVAF filter service, process the number of DSCBs 
indicated by FCLDSCBR,. 

3. Then, interpret the CVAF return code and CVSTAT. 

FCLIFLAG 

Define your request for ACCESS=READ with this flag byte. Any 
subsequent RESUME requests refer to a copy of these bits in the filter save 
area (FSA). 
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FCLILIST 

Set this bit to 1 if you specify a list of fully qualified data set names. 
Set it to if you specify a single partiaUy qualified data set name. 

FCLIORDR 

If you specify that CVAF return DSCB chains in the data set name 
sequence implied by the placement of the FCLDSN elements, set this 
bit to 1. Note that: 

• If you allow CVAF to determine the sequence of return for 
format- 1 DSCBs, you may realize a performance gam. 

• CVAF always returns DSCBs for a given data set in format- 1 , 
format-2, format-3 order. 

• If you specify a single partially-qualified data set name, CVAF 
filter does not use this field. 

FCL2FLAG 

CVAF filter indicates the following status conditions in this byte. 

FCL2SEQ 

CVAF filter sets this bit to 1 if it determines that its sequential VTOC 
access path is most efficient. If CVAF filter selects the direct VTOC 
access path, it sets this field to 0. 

FCL2SDIR 

CVAF filter sets this bit to 1 if storage limitations within its sequential 
VTOC access path require direct DSCB reads. CVAF initializes this 
bit to on each ACCESS=READ and ACCESS=RESUME request. 
You may test this bit when CVAF filter returns control to you, to 
determine if you must take some action to relieve the storage 
limitation. 
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The fonnat of the FCL entry is shown in Figure 19. 



Name 



Offset 



Bytes 



Description 



FCLDSN 


16(X»10') 


8 


FCLDSNST 


OO(X'OO') 


1 

X'OO' 

X'Ol' 

X'02' 

X'03' 

X'04' 

X'05' 


FCLDSNLG 


Ol(X'Ol') 


1 


FCL3FLAG 


02(X'02') 


1 


FCL3UPDT 




X'80' 
.xxxxxxx 


FCLDSNRV 


03(X'03') 


1 


FCLDSNA 


04(X'04') 


4 



Data set name information entry 

Data set name status 

Data set name not yet processed 

DSCBs returned successfully 

Data set name not found 

Error in DSCB cham. RESUME function recommended. 

Error in CVAFFILT processing. RESUME not recommended. 

Insufficient user buffer list elements. RESUME function 

recommended. 

Data set name length 

Flag byte 

This data set name processed during this invocation 

Reserved 

Reserved 

Data set name address 



Figure 19. Fonnat of a FUter Criteria List (FCL) Entry 



FCLDSN 

Contains data set name information. This, and the following fields are 
repeated in the FCL as a "set," as many times as indicated by the value in 
FCLCOUNT. 

FCLDSNST 

Indicates DSCB retrieval status. 

• CVAF filter initializes this byte to for ACCESS=READ 
requests. 

• CVAF filter updates this byte after processing this data set name 
for either ACCESS^READ or ACCESS=RESUME. 

• ACCESS = RESUME requests do not process data set names 
whose FCLDSNST field is non-zero, thus results may be 
unpredictable if you alter this field. 

• For partially-qualified data set name requests, CVAF filter does 
not post the FCLDSNST field until it has returned all DSCB 
chains for all qualifying data sets. CVAF filter posts the highest 
numeric value which applied during the its processing. 

• For fuUy-qualified data set name requests, CVAF filter returns a 
FCLDSNST byte for each data set name. If the value is greater 
than 1, CVAF filter has not returned any DSCBs for the 
associated data set name. 

See Figure 19 for the meanings of the possible values in this field. 
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FCLDSNLG 

Indicates length of data set name. You must provide this value. 

FCL3FLAG 

This is the. status flag byte associated with the data set name pointed 
to by FCLDSNA. 

FCL3UPDT 

This bit indicates that CVAF filter processed the associated 
data set name during the current invocation of CVAFFILT. 

• When initializing for either a READ or RESUME request, 
CVAF filter sets this bit to 0. 

• When CVAF filter has completed processing for the 
associated data set name, it sets this bit to 1. 

FCL3DSNRV 

Reserved, unused. 

FCLDSNA 

Specifies the address of a fully-qualified data set name, or, if this is the 
only data set name and FCLILIST is 0, a partially-qualified data set 
name. You must provide both this address and the storage area to 
which it points. 

Example of CVAFFILT Macro Sequences: The following example demonstrates the 
order in which you might issue CVAFFILT macro calls to: 

1 . Request the DSCBs for a list of data sets. 

2. Resume CVAFFILT processing interrupted because of insufficient user 
buffers. 

3. Release the kept filter save area. 

The example assumes the following conditions: 

• You are an authorized caller (that is, you are specifying a UCB address and 
IOAREA=KEEP). 

• You have initialized a CVAF buffer list as follows: 

— You have specified four buffers. 

— You have defined the buffer list address in your program with the label 
•BUFADDR*. 

- You will use the same buffer list for ACCESS=READ and 
ACCESS=RESUME processing. 

• You have initialized a filter criteria list (FCL) as follows: 

- FCLCOUNT = 6 (You are requesting DSCB chains for six data set 
names.) 



Chapter 1. Managing the Volume Table of Contents (VTOC) 57 



- FCLILIST = • 1 'B (The data set names are fully qualified.) 

- FCLIORDR = » 1 'B (You want the DSCB chains returned in the order 
implied by data set name elements in the FCL.) 

- You have initialized each of the six data set name elements such that they 
form a list requesting SYSl.A. SYS2.B, SYS3.C, SYS4.D, SYS5.E, and 
SYS6.F respectively. 

• The first five data sets have DSCB chain lengths or 1, 5, 2, 3, and 1 
respectively on the volume. 

• The sixth data set (SYS6.F) is not defined on the volume. 

To obtain an initialized CVPL, you could issue the following CVAFFILT macro 
(list form — does not call CVAF). This example requests the branch entry to 
CVAF and specifies that the caller is in supervisor state. 

CVPLIST CVAFFILT BRANCH= (YES,SUP) ,MF=L 

To obtain the first set of DSGB chains, you could issue the following CVAFFILT 
macro (execute form— calls CVAF). This example specifies that the filter save 
area is to be kept to allow for ACCESS=RESUME calls. The lOAREA is to be 
kept for improved efficiency. 

CVAFFILT ACCESS=READ , BUFLIST=buf addr , FCL=f claddr , 
UCB=ucbaddr , FLTAREA=KEEP , IOAREA=KEEP , 
MF=(E, CVPLIST) 

This CVAFFILT call would return DSCBs as follows: 

Buffer Contents of Buffer 

1 Format- 1 DSCB, SYSl.A 

2 Format- 1 DSCB, SYS3.C 

3 Format-3 DSCB, SYS3.C 

4 Undefined (unused) 

CVAF filter would provide return code = 4, CVSTAT = X'40' (RESUME 
recommended), and FCLDSCBR = 3 (CVAF would return a total of three 
DSCBs for the two data sets). CVAF would not return DSCBs for data set 
SYS2.B because its chain contains more DSCBs than the total number of buffers 
provided. To retrieve SYS2.B's DSCBs, you would have to specify at least five 
buffers AND execute another ACCESS=READ. (Even though CVAF allows you 
to specify a different buffer list for each READ OR RESUME, or modify the 
existing list between READ and RESUME calls, modifying the FCL would result 
in unpredictable results.) Buffer entry 4 would not have any DSCBs returned, 
because SYS4.D's DSCB chain size is larger than the number of remaining buffers. 
The FCL status information would be as follows: 

FCL3UPDT Comments 

DSCBs returned from this call 
DSCB chain exceeds total buffers 
DSCBs returned from this call 
DSCBs may be returned by RESUME 
DSCBs may be returned by RESUME 
DSCBs may be returned by RESUME 



DSN 


FCLDSNST 


FCL31 


SYSl .A 


1 


1 


SYS2.B 


5 


1 


SYS3.C 


1 


1 


SYS4.D 








SYS5.E 








SYS6.F 
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Because this CVAFFILT invocation recommends RESUME, and you specified 
FLTAREA=KEEP, you could use the following execute form of CVAFFILT to 
obtain more DSCB chains: 

CVAFFILT ACCESS=RESUME,MF= {E,CVPLIST) 

This CVAFFILT call would return DSCBs as follows: 

Buffer Contents of Buffer 

1 Format- 1 DSCB, SYS4.D 

2 Format-2 DSCB, SYS4.D 

3 Format-3 DSCB, SYS4.D 

4 Format- 1 DSCB, SYS5.E 

CVAF filter would provide return code = 0, C VST AT = (request completed), 
and would have updated the FCL status as follows: 

Comments 

DSCBs returned from prior call 
DSCB chain exceeds total buffers 
DSCBs returned from prior call 
DSCBs returned from this call 
DSCBs returned from this call 
Data set name not found 

FCLDSCBR would contain 4. (This CVAFFILT call returned a total of four 
DSCBs.) CVAF Filter would not return any DSCBs for SYS6.F, because its 
format- 1 DSCB cannot be found on the volume (FCLDSNST = '2'). 

Because this status indicates that CVAF Filter has returned all requested DSCBs, 
and you requested FLTAREA=KEEP and IOAREA=KEEP on the previous call, 
you should request the RLSE function as follows: 

CVAFFILT ACCESS=RLSE , FLTAREA=NOKEEP , IOAREA=NOKEEP , 
MF=(E,CVPLIST) 



DSN 


FCLDSNST 


FCL3UPDT 


SYS1.A 


1 





SYS2.B 


5 





SYS3.C 


1 





SYS4.D 


1 


1 


SYS5.E 


1 


1 


SYS6.F 


2 


1 



Obtaining Information from the VTOC Index 



You may use ACCESS«MAPDATA to obtain information contained in the space 
maps. "CVAFDSM Macro" on page 239 discusses detailed information about the 
CVAFDSM VTOC access macro. 

To count the number of unallocated VIRs in the VTOC index space map (VDCM), 
you must code COUNT=YES and MAP=INDEX. CVAF returns the number of 
unallocated VIRs m the 4-byte area specified by the CTAREA keyword. 

To count the number of format-0 DSCBs, you must code COUNT=YES and 
MAP=VTOC. CVAF returns the number of format-0 DSCBs in the VTOC map 
of DSCBs VMDS in the 4-byte area specified by the CTAREA keyword. 

To obtain one or more free space extents from the VTOC pack space map 
(VPSM), you must code COUNT=NO and MAP=VOLUME. CVAF returns the 
extents in the area specified by the EXTENTS keyword. Each extent is returned in 
a 5-byte XXYYZ format, the same as for a format-5 DSCB extent, where XX is 
the relative track address (RTA) of the fkst track of the extent, YY is the number 
of whole cylinders in the extent, and Z is the number of additional tracks in the 
extent. The RTA specified by your program to CVAF in the first (or only) extent 
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serves as a starting point for the VPSM search; the extent returned is the next free 
extent with a higher starting RTA than the one your program specified. 

If all the unallocated extents in the VPSM are supplied before filling in all the 
extents supplied, the remaining extents are set to zero. CVAF provides return code 
4 in register 15 and indicates end-of-data condition by putting a value of X*20' in 
the CVSTAT field. 



Diagnosing VTOC Errors 



Actions Taken When an Error Occurs 

These actions are taken if an error occurs: 



If an index structure error is detected, DADSM or CVAF causes the VTOC 
index to be disabled. The indexed VTOC bit is zeroed in the format-4 DSCB. 
A software error record is written to SYSl.LOGREC. A system dump is 
taken. The VTOC is converted to a nonindexed format at the next DADSM 
allocate or extend call. 

If a program check, machine check, or other error occurs while using a VTOC 
access macro, a SYSl.LOGREC message is written, and a system dump is 
taken. 

An error code is put in the CVSTAT field of the CVPL. The values and 
explanations of these error codes are listed in Appendix C, "VTOC Index 
Error Message and Associated Codes" on page 297. 



Recovering from System or User Errors 



Because an unauthorized user cannot modify a VTOC, neither the VTOC nor the 
VTOC index need be recovered from a user error caused by an unauthorized user. 

A system error affects a VTOC and VTOC mdex, probably by interrupting 
DADSM while it is updating, thus leaving the VTOC and/or the VTOC index in a 
partially updated state. Both the VTOC and the VTOC index are designed to 
allow DADSM to recover from such an interruption. 

For a nonindexed VTOC (or a VTOC with an mdex that has been disabled), a 
subsequent call to DADSM ALLOCATE or EXTEND causes VTOC convert 
routines to reestablish the free space (format-5 DSCBs). 

For an indexed VTOC, a subsequent call to any DADSM function causes the 
recovery of the previous interrupt (either by backing out or completing the 
interrupted function). 
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GTF Trace 



A trace function exists to trace all CVAF calls for VTOC index output I/O, all 
VTOC output I/O, and all VTOC index and space map modifications. For 
information on this function, see DFP Diagnosis. 



Listing a VTOC and VTOC Index 



You may obtain dump, formatted, or abridged listings of the VTOC and the VTOC 
index by using the LISTVTOC command of the EEHLIST utility program. 
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Chapter 2. Executing Your Own Channel Programs (EXCP) 



The execute-chaimel-program (EXCP) macro instruction provides you with 
complete control of the data organization based on device characteristics. This 
chapter contains a general description of the function and application of the EXCP 
macro instruction, accompanied by descriptions of specific control blocks and 
macro instructions used with EXCP. Factors that affect the operation of EXCP, 
such as device variations and program modification, are also discussed. 

Before reading this chapter, you should be familiar with system functions and with 
the structure of control blocks, as well as with the operational characteristics of the 
I/O devices required by your channel programs. Operational characteristics of 
specific I/O devices are described in IBM publications for each device. 

You also need to understand the information in these publications: 

• Data Administration Guide contains the standard procedures for I/O processing 
under the operating system. 

• Assembler H Version 2 Application Programming: Guide contains the 
information necessary to code programs in the assembler language. 

• Data Administration: Macro Instruction Reference describes the system macro 
instructions that can be used in programs coded in the assembler language. 

• Conversion Notebook describes the factors to consider when converting from 
MVS/370 at the MVS/SP Version 1 level to MVS/XA. 

The execute-channel-program (EXCP) macro instruction causes a supervisor-call 
interruption to pass control to the EXCP processor. (I/O process is the name we 
will use for the EXCP processor and the I/O supervisor. For our purposes, it's 
unnecessary to understand how input/output processing is divided between the 
two.) EXCP also provides the I/O supervisor with control information regarding a 
channel program to be executed. When an IBM access method is being used, an 
access method routine is responsible for issuing EXCP. If you are not using an 
IBM access method, you must issue EXCP in your program. (The EXCP macro 
instruction cannot be used to process SYSIN or SYSOUT data sets.) 

You issue EXCP primarily for I/O programming situations to which the standard 
access methods do not apply. If you are writing your own access method, you must 
include EXCP for I/O operations. EXCP must be used for processing 
nonstandard labels, including reading and writing labels and positioning magnetic 
tape volumes. 

To issue EXCP, you must provide a channel program (a list of channel command 
words) and several control blocks in your program area. The I/O process then 
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schedules I/O requests for the device you have specified, executes the specified 
I/O commands, handles I/O interruptions, directs error recovery procedures, and 
posts the results of the I/O requests. 



Using EXCP in System and Problem Programs 



This section explains the procedures performed by the system and the programmer 
when EXCP is issued by the routines of IBM access methods. The additional 
procedures you must perform when issuing EXCP yourself are then described by 
direct comparison. 



How the System Uses EXCP 



When using an IBM access method to perform I/O operations, the programmer is 
relieved of coding channel programs and constructing the control blocks necessary 
for the execution of channel programs. To permit I/O operations to be handled by 
an access method, the programmer need only issue the following macro 
instructions: 

• A DCB macro instruction that produces a data control block (DCB) for the 
data set to be retrieved or stored 

• An OPEN macro instruction that initializes the data control block and 
produces a data extent block (DEB) for the data set 

• A macro instruction (for example, GET or WRITE) that requests I/O 
operations 

Access method routines will then: 

1. Create a channel program that contains channel commands for the I/O 
operations on the appropriate device 

2. Construct an input/output block (lOB) that contains information about the 
chaimel program 

3. Construct an event control block (ECB) that is later posted with a completion 
code each time the channel program terminates 

4. Issue an EXCP macro instruction to pass the address of the lOB to the routines 
that initiate and supervise the I/O operations 

The I/O process consists of: 

5. Constructing a request queue element (RQE) for scheduling the request 

6. If the requestor is in a V=V address space, fixing the buffers so that they 
cannot be paged out and translatmg the requestor's virtual channel program 
into a real channel program 

7. Issuing a start subchannel (SSCH) instruction to cause the channel to execute 
the real channel program 
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8. Processing I/O interruptions and scheduling error recovery procedures when 
necessary 

9. Posting a completion code in the event control block after the channel program 
has been executed 

Note: If the requestor is an authorized program in a V=R address space, a real 
channel program is provided; thus, item 6 is not performed. 

The programmer is not concerned with these procedures and does not know the 
status of I/O operations until they are completed. Device-dependent operations 
are limited to those provided by the macro instructions of the particular access 
method selected. 



How To Use EXCP in Problem Programs 



To issue the EXCP macro instruction directly, you must follow the procedures that 
the access methods would perform, as summarized in items 1 through 4 of the 
preceding discussion. In addition to constructing and opening the data control 
block with the DCB and OPEN macro instructions, you must construct a channel 
program, an input/output block, and an event control block before you can issue 
EXCP. The I/O process generally handles items 5 through 9. 

After issuing EXCP, you should issue a WATT macro instruction, specifying the 
address of the event control block, to determine whether the channel program has 
terminated. If volume switching is necessary, you must issue an EOV macro 
instruction. When all processing of the data set has been completed, you must 
issue a CLOSE macro instruction to restore the data control block. 

All external interfaces for EXCP are compatible between MVS/370 and 
MVS/XA, except for the restrictions noted below. These restrictions relate only to 
the support of virtual and real addresses above 16 megabj^es. 

EXCP will be available to programs executing in either 24-bit or 31 -bit addressing 
mode. However, in order to maintain the required compatibility, the following 
restrictions apply: 

• EXCP will only support a 24-bit virtual storage interface. In addition, all areas 
related to I/O operations (for example, I/O buffers, channel command words, 
lOBs, DEBs, appendages, and so forth), must remain 24-bit virtual 
addressable. EXCP (channel command word translator) will allow 24-bit 
virtual I/O buffers to be fixed above 16-megabyte real. When a channel 
command word (CCW) references a real address above 16-megabyte, the 
CCW translator will build an indirect addressing word (IDAW) for that CCW. 
Note that this is not supported for format- 1 CCWs. All virtual addresses must 
be below 16-megabyte. For V=R users, CCWs and IDAWs must be below 
16-megabyte real. 

• Only format-O CCWs are accepted as input. 

• All user-specified appendage routines are given control in 24-bit addressing 
mode and must return in the same mode. 
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Note: Access methods run in 24-bit addressing mode. Users running in 31 -bit 
mode must interface to the access methods by using a user-written routine that is 
resident below 16-megabyte virtual (because the access methods will be able to 
return control only to a 24-bit addressable location). All addresses, buffers, 
parameters, control blocks, save areas and exit addresses must be below 
16-megabyte virtual. All access methods (except VSAM), for example, GET or 
PUT, must be called in 24-bit addressing mode. 



31-Bit IDAW Requirements 



A virtual channel program provided by the EXCP caller may have one or more 
CCWs with the IDA flag set and the address portion of these CCWs pointing to a 
single 4-byte IDAW. This EXCP function is referred to as virtual IDAWs. 

The 4-byte IDAW can contain a virtual address that ranges from to the maximum 
31 -bit address. Virtual IDAWs are supported on all virtual CCWs except: 

• Transfer in channel (TIC) commands. 

• All non data-transfer type commands: for example, recalibrate, rewind, set 
space, fold, block data check, no operation, control commands. 

• Read, read backward, and sense commands, with the skip flag set. 

The same addressing restrictions apply to EXCPVR inputs with the exception that 
31 -bit real data areas may be specified by the user-created CCWs through the use 
of IDAWs. All CCWs and IDAWs must be below 16-megabyte real. 

Only format-O CCWs are accepted as input. 

All other areas related to the EXCP/EXCPVR I/O operation (for example, 
CCWs, IDAWs, lOBs, DEBs, DCBs, appendages, and so forth) must remain 24-bit 
addressable. 

Note, however, that the EXCP processor will allow both 24-bit and 31 -bit virtual 
I/O buffers to be fixed above 16-megabyte real. 



How EXCP Operates in a V=R Address Space 



User-constructed channel programs for I/O operations of an authorized program in 
a V=R address space are not translated. Because the address space is V=R, any 
CCWs created by the user have correct real data addresses. (Translation would 
only re-create the user's channel program, so the CCWs are used dkectly.) 

Modification of an active channel program by data read in or by processor 
instructions is legitimate in a V=R address space, but not in a V=V address space. 
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EXCP Requirements 



Channel Program 



Control Blocks 



Input/Output Block (lOB) 



This section describes the channel program that you must provide in order to issue 
EXCP. This section also describes the control blocks that you must either directly 
construct or cause to be constructed by using macro instructions. 

All areas related to the EXCP/EXCPVR I/O operation (for example, CCWs, 
IDAWs, lOBs, DEBs, DCBs, appendages, and so forth) must remain 24-bit 
addressable. 

Note, however, that the EXCP processor will allow both 24-bit and 31 -bit virtual 
I/O buffers to be fixed above 16-megabyte real. 



The channel program supplied by you and executed through EXCP is composed of 
CCWs on doubleword boundaries. Each channel command word specifies a 
command to be executed and, for commands initiating data transfer, the area to or 
from which the data is to be transferred. 

Channel command word operation codes used with specific I/O devices can be 
found in IBM publications for those devices. All channel command word operation 
codes described in these publications can be used. In addition, both data chaining 
and command chaining may be used. 

To specify either data chaining or command chaining, you must set appropriate bits 
in the channel command word and indicate the type of chaining in the input/output 
block. Both data and command chaining should not be specified in the same 
channel command word; if they are, data chaining takes precedence. 

EXCP does not support channel programs that modify themselves, regardless of 
the method of modification: data chaining, command chaining, or a program to do 
the modification. The intended modification in virtual storage has no effect on the 
running real-channel program (see "Modification of a Channel Program during 
Execution" on page 70). 



When using EXCP, you must be familiar with the function and structure of the 
lOB, the ECB, the DCB, the DEB, and the IDAW. lOB and ECB fields are 
illustrated under "Control Block Fields" on page 88. DCB fields are illustrated 
under "Macro Specifications for Use with EXCP" on page 73. The handling of 
IDAWs is described under "SIO Appendage" on page 95. Descriptions of these 
control blocks follow. 



The input/output block is used for communication between the problem program 
and the system. It provides the addresses of other control blocks, and maintains 
information about the channel program, such as the type of chaining and the 
progress of I/O operations. You must define the input/output block and specify 
its address as the only parameter of the EXCP macro instruction. 
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Event Control Block (ECB) 



Data Control Block (DCB) 



Data Extent Block (DEB) 



The event control block provides you with a completion code that describes 
whether the channel program was completed with or without error. A WATT 
macro instruction, which can be used to synchronize I/O operations with the 
problem program, must identify the event control block. You must define the 
event control block and specify its address in the input/output block. 



The data control block provides the system with information about the 
characteristics and processing requirements of a data set to be read or written by 
the channel program. A data control block must be produced by a DCB macro 
instruction that includes parameters for EXCP. If you are not using appendages, a 
short DCB is constructed. Such a DCB does not support reduced error recovery. 
You specify the address of the data control block in the input/output block. 

All DCBs must be located in storage that is not fetch-protected, or, if the task is 
authorized, in storage that is in the key of the task (TCB KEY). 



The data extent block contains one or more extent entries for the associated data 
set and other control information. An extent defines all or part of the physical 
boundaries on an I/O device occupied by, or reserved for, a particular data set. 
Each extent entry contains the address of a unit control block (UCB) that provides 
information about the type and location of an I/O device. More than one extent 
entry can contain the same UCB address. For all I/O devices supported by the 
operating system, the data extent block is produced during execution of the OPEN 
macro instruction for the data control block. The system places the address of the 
data extent block into the data control block. All DEBs must be located in storage 
that is not fetch-protected, or, if the task is authorized, in storage that is in the key 
of the task (TCB key). Only authorized tasks (APF-authorized or TCB PKF=0-7) 
may build DEBs to be used for I/O operations. 



How the Channel Program Executes 



This section explains how the system uses your channel program and control blocks 
after you issue EXCP. 



Initiation of the Channel Program 



By issuing EXCP, you request the execution of the channel program specified in 
the input/output block. The I/O process validates the request by checking certain 
fields of the control blocks associated with this request. If the I/O process detects 
invalid information in a control block, it initiates abnormal termination procedures. 

The EXCP processor gets: 

• The address of the data control block from the input/output block 

• The address of the data extent block from the data control block 
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• The address of the unit control block from the data extent block 

It places the lOB, TCB, DEB, and UCB addresses and other information about the 
channel program into an area called a request queue element (RQE). (Unless you 
are providing appendage routines (described under "Appendages" on page 71) 
you should not be concerned with the contents of RQEs.) 

If you have provided an SIO (start I/O) appendage, the EXCP processor now 
passes control to it. The return address from the SIO appendage determines 
whether the EXCP processor must: 

• Execute the I/O operation normally, or 

• Skip the I/O operation. 

For a description of the SIO appendage and its linkage to the EXCP processor, see 
"Appendages" on page 71. 

If you are issuing EXCP from a V=V address space, the channel program you 
construct containis virtual addresses. Because channel subsystems cannot use 
virtual addresses, the EXCP processor must: 

• Translate your virtual channel program into one that uses only real addresses. 

• Fix in real storage the pages used as I/O areas for the data transfer operations 
specified in your channel program. 

The EXCP processor builds the translated (real) channel program in a portion of 
real storage. 

For direct access devices, specify the seek address in the input/output block. The 
I/O supervisor constructs a CCW chain to issue the seek and the set file mask 
specified in the data extent block, and to pass control to your real channel program. 

If your channel program begins with a locate-record CCW, the I/O process builds 
a define-extent CCW and passes control to your real channel program. (You 
cannot issue the initial seek, set file mask, or define extent CCWs. The file mask is 
set to prohibit seek-cylinder CCWs, or, if space is allocated by tracks, seek-head 
commands. If the data set is open for INPUT, write CCWs are also prohibited.) 

For a magnetic tape device, the I/O supervisor constructs a CCW chain to set the 
mode specified in the data extent block and passes control to your real channel 
program. (You cannot set the mode yourself.) 

If the I/O device is other than a direct access device or a magnetic tape device, the 
I/O supervisor then places the starting CCW of the channel program into the 
operation request block (ORB) and issues a start subchannel (SSCH) instruction. 
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Modification of a Channel Program during Execution 



Any problem program that modifies an active channel program with processor 
instructions or with data read in by an I/O operation must be run in a V=5R 
address space. It cannot run in a V=V address space because of the channel 
program translation performed by the I/O supervisor. (In a V=sV address space, 
an attempt to modify an active channel program affects only the virtual image of 
the channel program, not the real channel program being executed by the channel 
subsystem.) 

A program of this type can be changed to run in a V=V address space by issuing 
another EXCP macro for the modified portion of the channel program. 



Completion of Execution 



The system considers the chaimel program completed when it receives an 
indication of a channel-end condition in the subchannel status word (SCSW). 
Unless a CHE (channel-end) or ABE (abnormal-end) appendage directs otherwise, 
the request queue element for the channel program is made available, and a 
completion code is placed into the event control block. The completion code 
indicates whether errors are associated with channel end. If device end occurs 
simultaneously with chaimel end, errors associated with device end (that is, unit 
exception or unit check) are also accounted for. 

If device end occurs after chaimel end and if an error is associated with device end, 
the completion code in the event control block does not indicate the error. 
However, the status of the unit and chaimel is saved by the I/O supervisor for the 
device, and the UCB is marked as intercepted. The mput/output block for the 
next request directed to the I/O device is also marked as intercepted. The error is 
assumed to be permanent, and the completion code in the event control block for 
the intercepted request indicates mterception. The DCBIFLGS field of the data 
control block is also flagged to indicate a permanent error. Note that, if a 
write-tape-mark or erase-long-gap CCW is the last or only CCW in your channel 
program, the I/O process will not attempt recovery procedures for device end 
errors. In these circumstances, command chaining a NOP CCW to your 
write-tape^mark or erase-long-gap CCW ensures initiation of device-end error 
recovery procedures. 

To be prepared for device-end errors, you should be familiar with device 
characteristics that can cause such errors. After one of your chaimel programs has 
terminated, you should not release buffer space until you have determined that 
your next request for the device has not been intercepted. You may reissue an 
intercepted request. 



Interruption Handling and Error Recovery Procedures 



An I/O interruption allows the processor to respond to signals from an I/O device 
that indicate either termination of a phase of I/O operations or external action on 
the device. A complete explanation of I/O interruptions is contained in IBM 
System/ 3 70 Principles of Operation. For descriptions of interruption by specific 
devices, see the IBM publications for each device. 
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Appendages 



If error conditions are associated with an interruption, the I/O supervisor schedules 
the appropriate device-dependent error routine. The channel subsystem is then 
restarted with another request that is not related to the channel program in error. 
(The following paragraphs discuss "related" channel programs.) If the error 
recovery procedures f aU to correct the error, the system places ones in the first two 
bit positions of the DCBEFLGS field of the data control block. You are informed 
of the error by an error code in the event control block. 

If a channel program depends on the successful completion of a previous channel 
program (as when one channel program retrieves data to be used in building 
another), the previous channel program is caUed a "related" request. Such a 
request must be identified to the EXCP processor. To find out how to do this, see 
"Input/Output Block (lOB) Fields" on page 89 and "Purging and Restoring I/O 
Requests" on page 156. 

If a permanent error occurs in the channel program of a related request, the EXCP 
processor removes the request queue elements for all dependent channel programs 
from their queue and makes them available. 

The related request queue (RRQ) reflects the order in which request queue 
elements are removed from their queue. 

For all requests dependent on the channel program in error, the system places 
completion codes into the event control blocks. The DCBIFLGS field of the data 
control block is also flagged. Any requests for a data control block with error flags 
are posted complete without execution. To reissue requests dependent on the 
channel program in error, you must reset the first two bits of the DCBIFLGS field 
of the data control block to zeros. You then reissue EXCP for each channel 
program desired. 

With the IBM 3800 Printing Subsystem, a cancel key or a system-restart-required 
paper jam causes both a lost data indicator to be set in DCBIFLGS and a lost page 
count and channel page identifier to be stored in the UCB extension. (See JES3 
Data Areas, TSO/E Data Areas, and IBM 3800 Printing Subsystem Programmer's 
Guide.) 



The detailed information about appendages that appeared in this section has been 
moved to Data Facility Product: Customization. 

An appendage is a user-written routine that provides additional control over I/O 
operations. By using appendages, you can examine the status of I/O operations 
and determine the actions to be taken for various conditions. 
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Channel Programming Considerations 



Command retry is a function of the channel supporting the IBM 2305-2, 
3330/3333, 3340/3344, 3350, 3375, and 3380 direct access devices. When the 
channel subsystem receives a retry request, it repeats the execution of the CCW, 
requiring no additional input/output interrupts. For example, a control unit may 
initiate a retry procedure to recover from a transient error. 

A command retry during the execution of a channel program may cause any of the 
following conditions to be detected by the initiating program: 

• Modifying CCWs: A CCW used in a channel program must not be modified 
before the CCW operation has been successfully completed. Without the 
command retry function, a command was fetched only once from storage by a 
channel. Therefore, a program could determine through condition codes or 
program controlled interruptions (PCI) that a CCW had been fetched and 
accepted by the channel. This permitted the CCW to be modified before 
reexecution. With the command retry function, this cannot be done, because 
the channel will fetch the CCW from storage again on a command retry 
sequence. In the case of data chaining, the channel will retry commands 
starting with the first CCW in the data chain. 

• Program Controlled Interrupts (PCI): A CCW containing a PCI flag may cause 
multiple program-controlled interrupts to occur. This happens if the 
PCI-flagged CCW was retried during a command retry procedure and if a PCI 
could be generated each time the CCW is reexecuted. 

• Residual Count: If a channel program is prematurely terminated during the 
retry of a command, the residual count in the channel status word (CSW) will 
not necessarily indicate how much storage was used. For example, if the 
control unit detects a "wrong-length record" error condition, an erroneous 
residual count is stored in the CSW until the command retry is successful. 
When the retry is successful, the residual in the CSW reflects the correct length 
of the data transfer. 

• Command Address: When data chaining with command retry, the CSW may 
not indicate how many CCWs have been executed at the time of a PCI. For 
example: 

CCW# Channel Program 

1 Read, data chain 

2 Read, data chain 

3 Read, data chain, PCI 

4 Read, command chain 

In this example, assume that the control unit signals command retry on Read 
#3 and the processor accepts the PCI after the channel resets the command 
address to Read #1 because of command retry. The CSW stored for the PCI 
will contain the command address of Read #1 when the channel has actually 
progressed to Read #3. 

• Testing Buffer Contents on Data Read: Any program that tests a buffer to 
determine when a CCW has been executed and continues to execute based on 
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this data may get incorriect results if an error is detected and the CCW is 
retried. 



Macro Specifications for Use with EXCP 



If you are using the EXCP macro instruction, you must also use DCB, OPEN, 
CLOSE, and, in some cases, the EOV macro instruction. The parameters of the 
DCB, EOV, and EXCP macro instructions are described here. The parameters and 
different forms of the OPEN and CLOSE macro instructions are described in Data 
Administration: Macro Instruction Reference. A diagram of the data control block 
(DCB) is included in this section with the description of the DCB macro 
instruction. 



Definiiig Data Control Blocks for EXCP (DCB) 



The EXCP form of the DCB macro instruction produces a data control block that 
can be used with the EXCP macro instruction. You must issue a DCB macro 
instruction for each data set to be processed by your channel programs. (Notation 
conventions and format illustrations of the DCB macro instruction are given in 
Data Administration: Macro Instruction Reference.) DCB parameters that apply to 
EXCP may be divided into four categories, depending on the following portions of 
the data control block that are generated when they are specified: 

• Foundation block. This portion is required and is always 12 bjrtes in length. 
You must specify two of the parameters in this category. 

• EXCP interface. This portion is optional. If you specify any parameter in this 
category, 20 bytes are generated. 

• Foundation block extension and common interface. This portion is optional 
and is always 20 bytes in length. If this portion is generated, the 
device-dependent portion is also generated. 

• Device dependent. This portion is optional and is generated only if the 
foundation block extension and common interface portion is generated. Its 
size ranges from 4 to 20 bjrtes, depending on specifications in the DEVD 
parameter. However, if you do not specify the DEVD parameter (and the 
foundation extension and common interface portion is generated), the 
maximum 20 bj^es for this portion are generated. 

Some of the procedures performed by the system when the data control block is 
opened and closed (such as writing file marks for output data sets on direct access 
volumes) require information from optional data control block fields. You should 
make sure that the data control block is large enough to provide all information 
necessary for the procedures you want the system to handle. 

Figure 20 on page 75 shows the relative position of each portion of an opened 
data control block. The fields corresponding to each parameter of the DCB macro 
instruction are also designated, with the exception of DDNAME, which is not 
included in a data control block that has been opened. The fields identified in 
parentheses represent system information that is not associated with parameters of 
the DCB macro instruction. 
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Sources of information for data control block fields other than the DCB macro 
instruction are data definition (DD) statements, data set labels, and data control 
block modification routines. You may use any of these sources to specify DCB 
parameters. However, if a particular portion of the data control block is not 
generated by the DCB macro instruction, the system does not accept information 
intended for that portion from any alternative source. 

You may provide symbolic names for the fields in one or more EXCP DCBs by 
coding a DCBD macro to generate a dummy control section (DSECT). To map 
the common interface, foundation block extension, and foundation block, you code 
DSORG=XE. To map the foundation block and EXCP interface, you code 
DSORG=XA. You may code DSORG==(XA,XE) to map both. For further 
information, see Data Administration: Macro Instruction Reference. 



Foundation Block Parameters 



DDNAME=5ymfto/ 

The name of the data definition (DD) statement that describes the data set 
to be processed. This parameter must be given. 

MACRF=(E) 

The EXCP macro instruction is to be used in processing the data set. This 
operand must be coded. 

REPOS={Y I N} 

Magnetic tape volumes: This parameter indicates to the dynamic device 
reconfiguration (DDR) routine whether the user is keeping an accurate block 
, count. If the user is keeping an accurate block count, the DDR routine can 
attempt to swap the volume. (You must maintain the block count in the 
DCBBLKCT field.) 

Y — The user is keeping an accurate block count, and the DDR routine can 
attempt to swap the volume. 

N — The block count is unreliable, and the DDR routine cannot and will not 
attempt to swap the volume. 

If the operand is omitted, N is assumed. 



EXCP Interface Parameters 



EOEA=5ymZ)o/ 

2-byte identification of an EOE appendage that you have entered into 
SYSl.LPALIB or SYSl.SVCLIB. 

PCU=5y/wZ>o/ 

2-byte identification of a PCI appendage that you have entered into 
SYSl.LPALIB or SYSl.SVCLIB. 

S\0\=symbol 

2-byte identification of a SIO appendage that you have entered into 
SYSl.LPALIB or SYSl.SVCLIB. 
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The device— dependent portion of the data control 
block varies in length and format according to 
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Figure 20. Data Control Block (DCB) Format for EXCP (After OPEN) 



CENDA=^symbol 

2-byte identification of a CHE appendage that you have entered into 
SYSl.LPALIB or SYSl.SVCLIB. 

XENDA=:symbol 

2-byte identification of an ABE appendage that you have entered into 
SYSl.LPALIB or SYSl.SVCLIB. 
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OPTCD=Z 

indicates that, for magnetic tape (input only), a reduced error recovery 
procedure (5 reads only) will occur when a data check is encountered. It 
should be specified only when the tape is known to contain errors and the 
application does not require that all records be processed. Its proper use 
would include error frequency analysis in the SYNAD routine. Specification 
of this parameter will also cause generation of a foundation block extension. 
This parameter is ignored unless it was selected at system generation. 

IMSK=::va/ue 

Any specification indicates that the system will not use IBM-supplied error 
routines. 



Foundation Block Extension and Common Interface Parameters 



EXLST^address 

the address of an exit list that you have written for exception conditions. The 
format of the exit list is provided in Data Facility Product: Customization. 

EODAD=address 

the address of your end-of -data-set routine for input data sets. If this 
routine is not available when it is required, the task is abnormally terminated. 

DSORG=|PS I PO I DA I ISJ 

the data set organization (one of the following codes). Each code indicates 
that the format of the device-dependent portion of the data control block is 
to be similar to that generated for a particular access method: 



Code 


DCB Format for 


PS 


QSAM or BSAM 


PO 


BPAM 


DA 


BDAM 


IS 


QISAM or BISAM 



For direct access devices, if you specify PS or PO, you must maintain the 
following fields of the device-dependent portion of the data control block so 
that the system can write a file mark for output data sets: 

• The track balance (DCBTRBAL) field that contains a 2-byte binary 
number that indicates the remaining number of bytes on the current 
track. This number can be obtained from the system track algorithm 
routine. 

• The full disk address (DCBFDAD) field that indicates the location of 
the current record. The address is in the form MBBCCHHR. 

These fields are written into the format- 1 DSCB and are used by Open 
routines for staging MSS data sets. Staging is done only up through the last 
cylinder specified by these fields if the data set is reopened for OUTPUT, 
INOUT, OUTIN, OUTINX, or EXTEND. 

If you specify PO for a direct access device, the DCBDIRCT field will not be 
updated. Therefore, you should be careful when using EXCP with the 
STOW macro. 
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lOBAD=address 

the address of an input/output block (lOB). If a pointer to the current lOB 
is not required, you may use this field for any purpose. 

The following parameters are not used by the EXCP routines. They provide 
additional information that the system will store for later use by access methods 
that read or update the data set. 

RECFM=co^ 

the record format of the data set. (Record format codes are given in Data 
Administration: Macro Instruction Reference.) When writing a data set to be 
read later, RECFM, LRECL, and BLKSIZE should be specified to identify 
the data set attributes. LRECL and BLKSIZE can only be specified in a DD 
statement, because these fields do not exist in a DCB used by EXCP. 

BFTEK={S|E} 

the buffer technique, either simple or exchange. 

BFALN=|F|D} 

the word boundary alignment of each buffer, either fuUword or doubleword. 

BVFL= length 

the length in bytes of each buffer; the maximum length is 32767. 

BUFNO=number 

the number of buffers assigned to the associated data set; the maximum 
number is 255. See Chapter 10, "Specifying Buffer Numbers for DASD 
Data Sets" on page 229, for further details and performance considerations. 

BVFCB=address 

the address of a buffer pool control block, that is, the 8-byte field preceding 
the buffers in a buffer pool. 



Device-Dependent Parameters 



DEVD^ code 

the device in which the data set may reside. The codes are listed in order of 
descending space requirements for the data control block: 

Code Device 



DA 


Direct access 


TA 


Magnetic tape 


PR 


Printer 


PC 


Card punch 


RD 


Card reader 



Note: For MSS virtual volumes, DA should be used. 

If you do not want to select a specific device until job setup time, you should 
specify the device type requiring the largest area; that is, DEVD=DA. 

The following diagrams illustrate the device-dependent portion of the data control 
block for each combination of device type specified in the DEVD parameter and 
data set organization specified in the DSORG parameter. Fields that correspond to 
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device-dependent parameters in addition to DEVD are indicated by the parameter 
name. For special services, you may have to maintain the fields shown in 
parentheses. The special services are explained in the note that follows the 
diagram. 

Device-dependent portion of data control block when DEVD=DA and 
DSORG=PS: 



Reserved 


5 

DCBFDAD 




8 






13 

DCBDVTBL 


16 

DCBKEYLE 


17 

DCBDEVT 


18 
DCBTRBAL 



For output data sets, the system uses the contents of the full disk address 
(DCBFDAD) field, plus one, to write a file mark when the data control block is 
closed, provided the track balance (DCBTRBAL) field indicates that space is 
available. If DCBTRBAL is less than 8, the file mark is written on the next 
sequential track. You must maintain the contents of these two fields yourself if the 
system is to write a file mark. OPEN will initialize DCBDVTBL and DCBDEVT. 

Device-dependent portion of data control block when DEVD=DA and 
DSORG=DA: 



16 

DCBKEYLE 


18 

Reserved 



Device-dependent portion of data control block when DEVD=TA and 
DSORG=PS: 



12 



DCBBLKCT 



16 
DCBTRTCH 



17 



Reserved 



18 



DCBDEN 



19 



Reserved 



The system uses the contents of the block count (DCBBLKCT) field to write the 
block count in trailer labels when the data control block is closed or when the EOV 
macro instruction is issued. You must maintain the contents of this field yourself if 
the system is to have the correct block count. (Note: The I/O supervisor 
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increments this field by the contents of the lOBINCAM field of the lOB at the 
completion of each I/O request.) 

When using EXCP to process a tape data set open at a checkpoint, you must be 
careful to maintain the correct count; otherwise, the system may position the data 
set incorrectly when restart occurs. If REPOS=Y, the count must be maintained 
by you for repositioning during dynamic device reconfiguration. 

Device-dependent portion of data control block when DEVD=PR and 
DSORG=PS: 



16 

DCBPRTSP 


18 

Reserved 



Device-dependent portion of data control block when DEVD=PC or RD and 
DSORG=PS: 



16 

DCBMODE.DCBSTACK 


18 

Reserved 



The following DCB operands pertain to specific devices and may be specified only 
when the DEVD parameter is specified. 

KEYhEN=length 

for direct access devices, the length in bytes of the key of a physical record, 
with a maximum value of 255. When a block is read or written, the number 
of bytes transmitted is the key length plus the record length. 

DEN=va/Me 

for magnetic tape, the tape recording density in bits per inch: 





Density 




Vahie 


7-track tape device 


9-track tape device 


1 
2 
3 
4 


556 
800 


800 (NZRI) 
1600 (PE) 
6250 (GCR) 



NRZI — ^Non-retum-to-zero change to ones recording 
PE — ^phase encoded recording 
GCR — ^group coded recording 

If this parameter is omitted, the highest density available on the device is 
assumed. 

TRTCH=va/Me 

for 7-track magnetic tape, the tape recording technique- 
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Value Tape Recording Technique 

C Data conversion feature is available. 

E Even parity is used. (If omitted, odd parity is assumed.) 

T BCDIC to EBCDIC translation is required. 

MODE=value 

for a card reader or punch, the mode of operation. Either C (column binary 
mode) or E (EBCDIC code) may be specified. 

STACK=va/«e 

for a card punch or card reader, the stacker bin to receive cards, either 1 or 
2. 

PRTSP :=value 

for a printer, the line spacing, either 0, 1, 2, or 3. 



DSORG Parameter of the DCBD Macro 



In addition to the operands described in Data Administration: Macro Instruction 
Reference for the DSORG parameter of the DCBD macro, you may specify the 
following operands. 

DSORG= 

XA specifies a DCB with the EXCP interface section (including appendage 
names) 

X£ specifies a DCB with the foundation block extension 



Initializing Data Control Blocks (OPEN) 

The OPEN macro instruction initializes one or more data control blocks so that 
their associated data sets can be processed. You must issue OPEN for all data 
control blocks that are to be used by your channel programs. (A dummy data set 
may not be opened for EXCP.) Some of the procedures performed when OPEN is 
executed are: 

Reading in the JFCB (job file control block), unless the TYPE = J option of the 
macro instruction was coded 

Construction of the data extent block (DEB) 

Transfer of information from the JFCB and data set labels to the DCB 

Verification or creation of standard labels 

Tape positioning 

Loading of your appendage routines 

I The parameters and different forms of the OPEN macro instruction are described 

I in Data Administration: Macro Instruction Reference. 
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If you intend to process a multivolume direct data set, you must cause the open 
routines to build a data extent block for each volume and issue mount messages for 
them. This can be done by reading in the JFGB with a RDJFCB macro instruction 
and opening each volume of the data set. See " Using RDJFCB to Process a 
Multivolume Direct Data Set" on page 141 for an example of how to code a 
routine to do this, and "Reading and Modifying a Job File Control Block" on 
page 136 for further uses of the RDJFCB macro. 



Executing a Channel Program (EXCP) 



End of Volume (EOV) 



The EXCP macro instruction requests the initiation of the I/O operations of a 
channel program. You must issue EXCP whenever you want to execute one of 
your channel programs. The format of the EXCP macro instruction is: 



[symbol] 


EXCP 


iob-addr 



iob-addr — A-type address, (2-12), or (1) 

the address of the input/output block of the channel program to be 
executed. 



The EOV macro instruction identifies end-of-volume and end-of-data-set 
conditions. For an end-of-volume condition, EOV causes switching of volumes 
and verification or creation of standard labels. For an end-of-data-set condition, 
EOV causes your end-of-data set routine to be entered. Before processing trailer 
labels on a tape input data set, you must decrement the DCBBLKCT field. Your 
program issues EOV if switching of magnetic tape or direct access volumes is 
necessary, or if secondary allocation is to be performed for a direct access data set 
opened for output. 

For magnetic tape, you must issue EOV when either a tapemark is read or a 
reflective spot is written over. In these cases, bit settings in the 1-byte 
DCBOFLGS field of the data control block determine the action to be taken when 
EOV is executed. Before issuing EOV for magnetic tape, you must make sure that 
appropriate bits are set in DCBOFLGS. Bit positions 2, 3, 6, and 7 of 
DCBOFLGS are used only by the system; you are concerned with bit positions 0, 
1, 4, and 5. The use of these DCBOFLGS bit positions is as follows: 



BitO 



Bitl 



Bit 4 



Bits 



set to 1 indicates that a write command was executed and that a tapemark is 
to be written. 



indicates that a backward read was the last I/O operation. 



indicates that data sets of unlike attributes are to be concatenated. 



indicates that a tapemark has been read. 
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If bits and 5 of DCBOFLGS are both off when EOV is executed, the tape is 
spaced past a tapemark, and standard labels, if present, are verified on both the old 
and new volumes. The direction of spacing depends on bit 1. If bit 1 is off, the 
tape is spaced forward; if bit 1 is on, the tape is backspaced. 

If bit is on, but bit 5 is off, when EOV is executed, a tapemark is written 
immediately following the last data record of the data set. Standard labels, if 
specified, are created on the old and the new volume. 

After issuing EOV for sequentially organized output data sets on direct access 
volumes, you can determine whether additional space was obtained on the same or 
a different volume. You do this by examining the data extent block (DEB) and the 
unit control block (UCB). If neither the address of the UCB, as shown in the 
DEB, nor the volume serial number, as shown in the UCB, has changed, additional 
space was obtained on the same volume. Otherwise, space was obtained on a 
different volume. 

The parameters of the EOV macro instruction are: 



[symbol] 


EOV 


(deb addr \ acb addr) 
[,MODE=:{24|3in 



deb addr \ acb addr — A-type address, (2-12), or (1) 

the address of the data control block or access method control block that is 
opened for the data set. If this parameter is specified as (1), register 1 must 
contain this address. 

MODE={24|31} 

indicates whether the EOV parameter list may reside above or below the 16 
megabyte line in virtual storage. The modes are: 

24 

If you do not specify the MODE operand, this mode is assumed, The 
expansion of the EOV macro generates a parameter list of the 
standard form (4 bytes per entry). The parameter list must be below 
the 16 megabyte Une, but the calling program may be above the line. 
If your program is in 24-bit mode and you do not use a register to 
provide the address of the DCB or ACB, the DCB or ACB must be 
below the 16 megabjrte line. 

31 

The expansion of the EOV macro generates a parameter list in the 
31 -bit addressing mode format (8 bytes per entry). The parameter list 
may reside above or below the 16 megabyte line. The first byte (byte 
0) in each entry contains option information and the last four bytes 
(bytes 4-7) contain the 4-byte DCB or ACB address. The DCB (and 
all ACBs except VSAM/VTAM ACBs) must be below the 16 
megabyte line; therefore, byte 4 must be zeros. Bytes 1 through 3 must 
also be zeros. 

Note: Failure to provide a DCB below the 16 megabyte line causes an 
ABEND SOD. 
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Note: To determine how the system disposes of a tape volume when an EOV 
macro is issued, see the description of the DISP parameter of the OPEN macro in 
Data Administration: Macro Instruction Reference. 



Restoring Data Control Blocks (CLOSE) 

The CLOSE macro instruction restores one or more data control blocks so that 
processing of their associated data sets can be terminated. You must issue CLOSE 
for all data control blocks that were used by your channel programs. Some of the 
procedures performed when CLOSE is executed are: 

• Release of data extent block (DEB) 

• Removal of information transferred to data control block fields when OPEN 
was executed 

• Verification or creation of standard labels 

• Volume disposition 

• Release of progranuner-written appendage routines 

When CLOSE is issued for data sets on magnetic tape volumes, labels are 
processed according to bit settings in the DCBOFLGS field of the data control 
block. Before issuing CLOSE for magnetic tape, you must set the appropriate bits 
in DCBOFLGS. The significant DCBOFLGS bit positions are listed in the EOV 
macro instruction description. 

The parameters and different forms of the CLOSE macro instruction are described 
in Data Administration: Macro Instruction Reference. 

Assigning an Alternate Track and Copying Data from the Defective Track (ATLAS) 

A program that uses the EXCP macro instruction for input and output and that is 
APF authorized may, during the execution of the program, use the ATLAS macro 
instruction to obtain an alternate track and to copy a defective track onto the 
alternate track. With the use of ATLAS, the program can recover from permanent 
(hard) errors encountered in the execution of the following types of I/O 
commands: 

• Search ID. 

• Write. (The error condition must be confirmed during the execution of the 
channel program by a CCW that checks the data written.) 

• Read count. Errors in the CCHHR part of the count area can be recovered 
from, unless the record is the home address or record zero. Errors in the KDD 
part of the count area cannot be recovered from, unless the user has identified 
the defective record. 

Note: ATLAS may be used for all direct access devices with the exception of MSS 
volumes (3330V). 
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Your DCB must include the DCBRECFM field, and the field must show whether 
the data set is in the track overflow format. If it is, recovery from errors in last 
records on tracks depends on your identifying the track overflow record segments. 

Recovery takes the form of obtaining a good alternate track and copying the 
defective track onto the good alternate one. Unless a reexecution of the channel 
program by ATLAS can correct the defect, the user should examine, and if 
necessary replace, defective records in a subsequent job if the data set is to be 
processed again. 

The format is: 



{symbol\ 


ATLAS 


PARMADR={a^ri 
1,CHANPRG={R|NR}1 
1,CNTPTR={P|F}1 
[,WRITS=|YES|NO}l 



PARMADR 

Address of a parameter address list of the following format: 



Address of lOB for the channel program that 
encountered the error 



Address of count area field 



The count area field contains the CCHHRKDD of a defective record or the 
CCHH of a track that is to be copied. 

addr — A -type address, (2-12), or (I) 

CHANPRG=|R|NR} 

specifies whether the channel program that encountered the error can be 
executed again. 

R Channel program may be executed again by ATLAS. Before 

permitting reexecution of the channel program by ATLAS, you must 
reset the error indications of the previous execution fields in the 
DCBIFLGS. (See the example of the use of ATLAS below.) 

NR Channel program may not be executed again. 

If this parameter is omitted, R is assumed. 

CNTPTR 

specifies whether the count area field contains a full count area 
(CCHHRKDD) or a partial count area (CCHH). 



84 MVS/XA System-Data Administration 



Using ATLAS 



P Part of the count area (the CCHH address of the track to be copied). 

F Full count area (CCHHRKDD count of the record that was found 
defective). 

If this parameter is omitted, P is assumed. 

WRITS 

track overflow segment identification. 

If your data set is in the track overflow format, this identification determines 
recovery from errors in last records on tracks. 

YES If this is the last record on the track, it is a segment other than the last 
of a track overflow record. 

NO If this is the last record on the track, it is the last or only segment of a 
track overflow record. 

If this parameter is omitted, it is assumed that it cannot be established 
whether a last record is a segment of an overflow record. 



If a channel program encounters a unit check condition (shown in the CSW) in its 
execution, the EXCP processor program will place the sense bytes in the lOB. 
ATLAS can be used to recover from sense conditions shown by the following bit 
settings: 

lOBSENSO X'08' Data check 

lOBSENS 1 X ' 80 ' Permanent 

Also, before using ATLAS, you must reset error indications as follows: 

NI DCBIFLGS , X • 3F ' Reset the DCBIFLGS error indications. 

The ATLAS program will attempt to find a good alternate track and will attempt to 
copy the defective track onto the good track, including all error conditions in either 
key or data areas. The error conditions may be rectified by reexecuting the 
channel program or through the use of the lEHATLAS utility program in a 
subsequent step. 

Example: The following illustrates the use of the ATLAS macro instruction. 
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EXCP 


MYIOB 




WAIT 


ECB=MYECB 




TM 


MYECB,X'7F' 


1 


BO 


NEXT 




TM 


I0BCSW+3,X' 


'02' 


BZ 


OTHER 




TM 


IOBSENS0,X' 


'08' 


BNO 


OTHER 




TM 


lOBSENS 1 , X " 


•80' 


BNO 


OTHER 




NI 


DCBIFLGS^X' 


•3F' 



TEST FOR I/O ERROR 
NO, SUCCESSFUL, GO TO 
ANOTHER ROUTINE 
UNIT CHECK 
NO, DO OTHER ERROR 
PROCESSING 
DATA CHECK 
NO, CAN'T HANDLE 
PERMANENT 
NO, CAN'T HANDLE 
RESET ERROR 
INDICATORS 
ATLAS PARMADR=THERE , CHANPRG=R 



Operation of the ATLAS Program 

The ATLAS program (SVC 86): 



• Establishes the availability and address of the next alternate track from the 
format-4 DSCB of the VTOC. 

• Brings all count fields from the defective track into storage to establish the 
description of the track. 

• Initializes the alternate track. (Writes the home address and record zero.) 

• Brings the key and data areas of each record into storage, one at a time, and 
combines them with their new count area to write the complete record onto the 
alternate track. 

• When the copying is finished, chains the alternate to the defective track and 
updates the VTOC. 

Control is returned to your program at the next executable instruction following the 
ATLAS macro instruction. 



Return Codes from the ATLAS Program 



The success of the ATLAS macro instruction can be determined by examining the 
contents of register 15, which will contain one of the return codes described below. 
If register 15 contains decimal 0, 36, 40, or 44, the contents of register may be 
significant. 
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Code Meaning 

O(X'OO') Successful completion. Key and data areas have been copied from 
the defective track onto a good alternate one. The only error 
encountered was in the record identified by the user's CCHHRKDD 
value. 

If the channel program is reexecutable, it has been successfully 
reexecuted. 

4(X'04' ) This device type does not have alternate tracks that can be assigned 
by programming. 

8(X'08') All alternate tracks for the device have been assigned. 

12(X'0C') A request for storage (GETMAIN macro instruction) could not be 
satisfied. 

16(X' 10') All attempts to initialize and transfer data to an alternate track failed. 
The number of attempts made is equal to 10% of the assigned 
alternates for the device. 

20(X' 14') The type of error shown by the sense byte cannot be handled 

through the use of the ATLAS macro instruction. The condition is 
other than a data check (in the count or data areas) or a missing 
address marker. 

24(X' 1 8 ' ) The format-4 DSCB of the VTOC cannot be read; therefore 
alternate track information is not available to ATLAS. 

28(X' IC ) The record specified by the user was the format-4 DSCB, and it 
could not be read. 

32(X' 20' ) An error found in count area of last record on the track cannot be 
handled because last-record-on-track identification is not supplied. 

36(X' 24' ) An error was encountered when reading or writing the home address 
record or record zero. No error recovery has taken place. 

If register contains X'Ol 00 00 00', the defect is in record zero. 

40(X'28') Successful completion. Key and data areas have been copied from 

the defective track onto a good alternate one. However, the alternate 
track may have records with defective key or data areas. Register 
identifies the first three found defective as follows: 

n R R R 

n — The number of record numbers that follow (0, 1, 2, or 3). 
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Code Meaning 

R — ^The hexadecimal number of the record found defective but 
copied anyway. 

If the channel program is reexecutable, it has been successfully 
reexecuted. 

44(X*2C') Errors encountered and no alternate track has been assigned. The 
return parameter register (register 0) will contain the R of a 
maximum of three error records. 

Error conditions that return this code are: 

• ATLAS received an error indication for a record with a data 
length in the count field of zero. Recovery was not possible 
because a distinction cannot be made between an EOF record 
and an invalid data length. 

• An error occurred while reading the count field of a record, and 
the KDD (key length-data length) was found to be defective. 

• More than three records on the specified track contained errors 
in their count fields. 

48(X'30') No errors found on the track, no alternate assigned. ATLAS will not 
assign an alternate unless a track has at least one defective record. 

52(X'34') I/O error in reexecuting user's channel program. A good alternate is 
chained to the defective track, and data has been transferred. The 
user's control blocks will give indication of the error condition 
causing failure in reexecution of the channel program. 

56(X' 38 ' ) The DCB reflects a track overflow data set, but the UCB device type 
shows that the device does not support track overflow. 

60(X'3C') The CCHH of the user-specified count area is not within the extents 
of the data set. 

64(X'40') The device is an MSS virtual device, which is not supported. 



Control Block Fields 



The fields of the input/output block, event control block, and data extent block are 
illustrated and explained here; the data control block fields are described with the 
parameters of the DCB macro instruction under "EXCP Requirements" on 
page 67. 
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Input/Output Block (lOB) Fields 



The input/output block (lOB) is not automatically constructed by a macro 
instruction; it must be defined as a series of constants and must be on a fullword 
boundary. For unit-record and tape devices, the lOB is 32 bytes in length. For 
direct access, teleprocessing, and graphic devices, 8 additional bytes must be 
provided. You may want to use the system mapping macro lEZIOB, which 
expands into a DSECT, to help in constructing an lOB. 

In Figure 21 on page 90 the diagonaUy ruled areas indicate fields in which you 
must specify information. The other fields are used by the system and must be 
defined as all zeros. You may not place information into these fields, but you may 
examine them. 

lOBFLAGl (1 byte) 

You must set bit positions 0, 1, and 6. One-bits in positions and 1 indicate 
data chaining and command chaining, respectively. (If both data chaining 
and command chaining are specified, the system does not use error recovery 
routines except for the direct access devices.) A one-bit in position 6 
indicates that the channel program is not a "related" request; that is, the 
channel program is not related to any other channel program. If you intend 
to issue an EXCP macro with a BSAM, QSAM, or BPAM data control 
block, you may want to turn on bit 7 to prevent access-method appendages 
from processing the I/O request. 

IOBFLAG2 (1 byte) 

If you set bit 6 in the lOBFLAGl field to zero, bits 2 and 3 in this field must 
then be set to: 

• 00, if any channel program or appendage associated with a related 
request might modify this lOB or channel program. 

• 01, if the conditions requiring a 00 setting don't apply, but the CHE or 
ABE appendage might retry this channel program if it completes 
normally or with the unit-exception or wrong-length-record bits on in 
the CSW. 

• 10 in all other cases. 

The three combinations of bits 2 and 3 represent the three kinds of related 
requests, known as type 1 (00), type 2 (01), and type 3 (10). The type you 
use determines how much the EXCP processor can overlap the processing of 
related requests. Type 3 allows the greatest overlap, normally making it 
possible to quickly reuse a device after a channel-end interruption. (Related 
requests that were executed on a pre-MVS system are executed as type-1 
requests if not modified.) 

lOBSENSO and lOBSENSl (2 bytes) 

are placed into the input/output block by the EXCP processor when a unit 
check occurs. On occasion, the system is unable to obtain any sense bytes 
because of unit checks when sense commands are issued. In this case, the 
system simulates sense bytes by moving X' lOFE' to lOBSENSO and 
lOBSENSl. 
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0(0)/ 

////// 
////// 



0BFLAG1 



lOBECBCC 



8(8) 



I0BFLAG3 



0BFLAG2 



lOBSENSO 



I0BSENS1 



////////////////////////////////////// 
/////////////// lOBECBPT ///////////// 
////////////////////////////////////// 



12(C) 



lOBCSW 



16(10) 



lOBSIOCC 



20(1^) 



Reserved 



24(18) 



OBRESTR 



////////////////////////////////////// 

miiiimiini iobstart ///////////// 
////////////////////////////////////// 



////////////////////////////////////// 

/////////////// IOBDCBPT lltllllllllll 

i/nniniimiiiiiiiiininimnmi 



OBRESTR+1 



28(1C) ///////////////////////// 
II 1 1 nil II II lOBINCAM III II III II 
llllllllllllllllllllllllllllllll 



32(20) ////////// 
/// lOBSEEK // 
/ (first byte, M) 



lOBERRCT 



► Direct Access, Teleprocessing, and 
-J Graphic Devices 



33(21 ) /////////////////////////////// 
llllllllllllllllllllllllllllllllllllll 
llllllllllllllllllllllllllllllllllllll 
III lOBSEEK //// 

lllllllllllllllllllllll (second through eighth bytes, //// 
/////////////////////// BBCCHHR) //// 

I III nil II I II I II mill II mill III I nil I III III mil I i^^kii) 



► All 
Devices 



I Direct 
I Access 
► Storage 

J Devices 
(DASD) 



Figure 21. Input/Output Block (lOB) Format 



lOBECBCC (1 byte) 

the first byte of the completion code for the channel program. The system 
places this code in the high-order bjrte of the event control block when the 
channel program is posted complete. The completion codes and their 
meanings are listed under "Event Control Block (ECB) Fields" on page 92. 

lOBECBPT (3 bytes) 

the address of the 4-byte event control block you have provided. 



IOBFLAG3 (1 byte) 

is used only by the system. 
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lOBCSW (7 bytes) 

the low-order seven bytes of the channel status word that are placed into this 
field each time a channel-end or PCI interruption occurs. 

lOBSIOCC (1 byte) 

in bits and 1, the instruction-length code; in bits 2 and 3, the start 
subchannel (SSCH) condition code for the instruction the system issues to 
start the channel program; and, in bits 4 through 7, the program mask. 

lOBSTART (3 bytes) 

the starting address of the channel program to be executed. 

Reserved (1 byte) 

used only by the system. 

lOBDCBPT (3 bytes) 

the address of the data control block of the data set to be read or written by 
the channel program. 

lOBRESTR (1 byte) 

used by the system for volume repositioning in error recovery procedures. 

IOBRESTR+1 (3 bytes) 

if a related channel program is permanently in error, used by the system to 
chain together lOBs that represent dependent channel programs. To learn 
more about the conditions under which the chain is built, see "Interruption 
Handling and Error Recovery Procedures" on page 70. 

lOBINCAM (2 bytes) 

for magnetic tape, the amount by which the block count (DCBBLKCT) field 
in the device-dependent portion of the data control block is to be 
incremented. You may alter these bytes at any time. For forward 
operations, these bj^tes should contain a binary positive integer (usually +1); 
for backward operations, they should contain a binary negative integer. 
When these bytes are not used, all zeros must be specified. 



Reserved (2 bytes) 

used only by the system. 



lOBSEEK (first byte, M) 

for direct access devices, the extent entry in the data extent block that is 
associated with the channel program (0 indicates the first entry; 1 indicates 
the second, and so forth). For teleprocessing and graphic devices, it contains 
the UCB mdex. 

lOBSEEK (last 7 bytes, BBCCHHR) 

for direct access devices, the seek address for your channel program. 
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Event Control Block (ECB) Fields 



You must define an event control block (ECB) as a 4-byte area on a fullword 
boundary. When the channel program has been completed, the input/output 
supervisor places a completion code containing status information into the ECB 
(Figure 22 on page 93). Before examining this information, you must test for the 
setting of the "complete bit." If the complete bit is not on, and your problem 
program cannot perform other useful operations, you should issue a WAIT macro 
instruction that specifies the event control block. Under no circumstances should 
you construct a program loop that tests for the complete bit. 



Data Extent Block (DEB) Fields 



The data extent block (DEB) is constructed by the system when an OPEN macro 
instruction is issued for the data control block. You may not modify the fields of 
the DEB, but you may examine them. 



Executing Fixed Channel Programs in Real Storage (EXCPVR) 



The EXCPVR macro instruction provides you with the same functions as the 
EXCP macro instruction (that is, a device-dependent means of performing 
input/output operations). In addition, it allows your program to improve the 
efficiency of the I/O operations in a paging environment by translating its own 
virtual channel programs to real channel programs. Authorized programs are 
allowed to execute in a V=V area and provide the EXCP processor with real 
channel programs. This eliminates the translation of channel programs by the 
EXCP processor. The program issuing the EXCPVR must remain in authorized 
state until the completion of the channel programs. 

Problem programs are authorized to use the EXCPVR macro instruction under the 
authorized program facility (APE). A description of how to authorize a program 
can be found in Supervisor Services and Macro Instructions. 



[symboil 


EXCPVR 


iob-addr 



iob-addr — A-type address, (2-12), or (1) 

the address of the input/output block of the channel program to be 
executed. 

To use EXCPVR, you must do all the things you would do to execute an EXCP 
request; in addition you must: 

1. Code PGFX=YES in the DCB associated with the EXCPVR requests and 
provide a page-fix (PGFX) appendage by specifying SIOA=symbol in the 
DCB. 

2. Fix the data area that contains your channel program, the data areas that are 
referred to by your channel program, your PCI appendage (if your program 
can generate program-controlled interrupts), and any area referred to by your 
PCI appendage. To cause EXCP to fix these data areas, you build a list that 
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WAIT bit=0 



COMPLETE blt=1 



Remainder of completion code 



bit 




1 



31 



Wait bit 

A one bit in this position indicates that the WAIT macro instruction has been 
issued, but the channel program has not been completed. 

Complete bit 

A one bit In this position indicates that the channel program has been completed; 
if it has not been completed, a zero bit is in this position. 

Completion code 

This code, which includes the wait and complete bits, may be one of the following 
4— byte hexadecimal expressions: 

CODE MEANING 

7F000000 The channel program has terminated without error. 

41000000 The channel program has terminated with a permanent error. 

42000000 The channel program has terminated because a direct access extent address 
has been violated. 

44000000 The channel program has been intercepted because of a permanent error 

associated with a device end for the previous request. You may 
reissue the EXCP macro instruction to restart the channel 
program. 

48000000 The request queue element for a channel program has been made available 
after it has been purged. 

4B000000 One of the following errors occurred during error recovery processing for 
a tape device. 

• The CSW command address in the I OB is zeros. 

• An unexpected load point was encountered. 

4F000000 Error recovery routines have been entered because of direct access error 
but are unable to read the home address or record 0. 

Figure 22. Event Control Block (ECB) after Posting of Completion Code (EXCP) 
< 

contains the addresses of these virtual areas. You should build the list in your 
PGFX appendage. 

3. Determine whether the data areas in virtual storage specified in the address 
fields of your CCWs cross page boundaries. If they do, you must build an 
indirect data address list (IDAL) and put the address of the IDAL in the 
affected COW. 

4. Translate the addresses in your CCWs from virtual to real addresses. 

All other areas related to the EXCP/EXCPVR I/O operation (that is, CCWs, 
IDAWs, lOBs, DEBs, DCBs, appendages, and so forth) must remain 24-bit 
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addressable. Note, however, that the EXCP processor will allow both 24-bit and 
31 -bit virtual I/O buffers to be fixed above 16 megabytes real. 

Items 3 and 4 must be done in your start-I/O (SIO) appendage. A description of 
the SIO appendage is presented under "Appendages" on page 71. 



Building the List of Data Areas to Be Fixed 



The EXCP processor expects programs using the EXCPVR macro instruction to 
pass a list of data areas to be fixed. This list is to be buUt in the PGFX appendage, 
as described below. 

The data areas you must fix in real storage (if not akeady fixed in real storage) are: 

1. The channel program. If the channel program is akeady in a fixed subpool, it 
does not have to be fixed. 

2. The data areas to which your channel program will write and from which your 
channel program will read. If the data areas are already in a fixed subpool, they 
do not have to be fixed. 

3. The PCI appendage, if used, and any areas accessed by the PCI appendage 
(DEB, lOB, and so forth). 

EXCPVR users can specify 31 -bit real data areas by creating CCWs through the 
useoflDAWs. 



Page Fix (PGFX) and Start-I/O (SIO) Appendage 



Page-Fix List Processang 



This appendage consists essentially of two independent appendages. The complete 
appendage can be viewed as a re-enterable subroutine having two entry points, one 
for the SIO appendage and one for the PGFX appendage. 

The SIO entry point is located at offset in the subroutine; any other location in 
the appendage may be branched to from this entry point. The entry point of the 
PGFX appendage is at offset +4 in the SIO subroutine, which is set in register 15 
as the entry point of the PGFX appendage. 

Page Fix (PGFX) Appendage: The purpose of this appendage is to list all the areas 
that must be fixed to prevent paging exceptions during the execution of the current 
I/O request. This appendage may be entered more than once. However, each time 
it is entered, it must create the same list of areas to be fixed. The appendage may 
use the 16-word save area pointed to by register 13. Registers 10, 11, and 13 may 
be used as work registers. 



Each page-fix entry placed in the list by the appendage must have the following 
doubleword format: 
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|o 


1 31|32 


33 631 





Starting virtual 
address of area 
to be fixed 





Ending virtual 
address of area 
to be fixed + 1 







On return from your PGFX appendage to the EXCP processor (via the return 
address provided in register 14), register 10 must point to the first page-fix entry 
and register 1 1 must contain the number of page-fix entries in the work area. The 
EXCP processor then fixes the pages corresponding to the areas Usted by the 
PGFX appendage. The pages remain fixed until the associated I/O request 
terminates. 

If either the channel end appendage or the abnormal end appendage returns via the 
return address in register 14 plus 8, the PGFX appendage is not normally 
reentered. Instead, the SIO appendage is entered, and the page-fix list built by the 
PGFX appendage is still active. However, the PGFX appendage is entered after 
either the channel end appendage or the abnormal end appendage returns via the 
return address in register 14 plus 8 when a PURGE macro has been issued (for 
instance, when a storage swap has occurred). In this case, when I/O is restored, 
the PGFX appendage is entered. 

Note: The page-fix list must be in page-fixed storage. 

SIO Appendage: If you are using EXCPVR to execute your channel program, you 
must translate the virtual addresses in the operands of your channel program to real 
addresses. This should be done in your SIO appendage. If indirect data addressing 
is required, the SIO appendage should also build the indirect data address lists 
(IDALs) and turn on the IDA indicators in the associated CCWs. 

Translating Virtual Addresses and Building the IDAL: You must convert the virtual 
addresses in the channel program to real addresses. You must also check the areas 
whose addresses appear in bits 8 through 31 of your CCWs to determine whether 
the data areas cross 2K-byte boundaries. If they do, you must provide an entry in 
the IDAL for each 2K-byte boundary crossed. The channel subsystem uses the 
IDAL to identify the address where it will continue reading or writing when a 
2K-b)rte boundary is crossed during a read or write operation. The IDAL must 
contain real addresses when it is processed by the channel. 

In MVS/XA, the LRA instruction returns a 31 -bit real address regardless of the 
addressing mode. You must be careful when you construct the ID AW to ensure 
that the real storage obtained by GETMAIN (or branch entry) is below 16 
megabytes. Do your page fixing before you issue the LRA. (See Supervisor 
Services and Macro Instructions or System Macros and Facilities for information on 
how to obtain real storage below 16 megabytes real.) 
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CCW 
















Command 
Code 


Address of the 
IDAL 


04 


imiiiiii 

llllllllll 


Byte 
Count 




7 8 


31 32 39 ^0 47 48 
IDAL 











First Indirect Data 
Address Word 




4 


Second Indirect Data 
Address Word 




8 


Subsequent Indirect 
Data Address Word 



T>lotes: 

1 . You must put one entry in the IDAL for each 2K-byte page boundary your data 
area crosses. 

2. If the CCW has an IDAL address rather than a data address, bit 3 7 must be set 
to signal this to the channel. 

3. The maximum number of entries needed in the IDAL is determined from the 
count in the CCW as follows: 

Number of IDAL entries=((CCW byte-count - l)/2048) + L 
(Round up division to next highest integer if remainder is not zero.) 

The number of IDAL entries required ultimately depends on the number of 
2K-byte boundaries crossed by the data. For example, if your data is 800 bytes 
long and does not cross a 2K-byte page boundary, no IDAL entries are required. 
If your data crosses a 4K-byte page boundary, then two IDAL entries are required. 
If your data is 5000 bytes long, at least two IDAL entries are required. If your 
data crosses two 4K-byte page boundaries, four IDAL entries are required. 

The first indirect address is the real address of the first byte of the data area. The 
second and subsequent indirect addresses are the real addresses of the second and 
subsequent 2K-byte boundaries of the data area. 
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For example, if the data area real address is X'707FF' and the byte count is 

X' 1802', the IDAL would contain the following real addresses (assuming the real 

addresses are contiguous, which may not always be the case): 

707FF 
70800 
71000 

If the data area real address is X'707FF' and the byte count is X' 800', the ffiAL 
would contain the following addresses: 

707FF 
70800 
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Chapter 3. Reading from and Writing to Direct Access Devices (XDAP) 

Execute direct access program (XDAP) is a macro instruction that you may use to 
read, verify, or update a block on a direct access volume. This chapter explains 
what the XDAP macro instruction does and how you can use it. The control block 
generated when XDAP is issued and the macro instructions used with XDAP are 
also discussed. 

Because most of the specifications for XDAP are similar to those for the execute 
channel program (EXCP) macro instruction, you should be familiar with the 
"Executing Your Own Channel Programs (EXCP)" chapter of this publication, 
and with the information contained in Data Administration Guide that provides 
how-to information for using the access method routines of the system control 
program. 

If you are not using the standard IBM data access methods, you can, by issuing 
XDAP, generate the control information and channel program necessary for 
reading or updating the records of a data set. (However, XDAP cannot be used to 
read, verify, or update a SYSIN or SYSOUT data set.) 

You cannot use XDAP to add blocks to a data set, but you can use it to change the 
keys of existing blocks. Any block configuration and any data set organization can 
be read or updated. 

Although the use of XDAP requires less storage than do the standard access 
methods, it does not provide many of the control program services that are included 
in the access methods. For example, when XDAP is issued, the system does not 
block or unblock records and does not verify block length. 

To issue XDAP, you must provide the actual track address of the track containing 
the block to be processed. You must also provide either the block identification or 
the key of the block, and specify which of these is to be used to locate the block. If 
a block is located by identification, both the key and data portions of the block 
may be read or updated. If a block is located by key, only the data portion can be 
processed. 

For additional control over I/O operations, you may write appendages that must be 
entered into the LPA library. Descriptions of these routines and their coding 
specifications are included under Chapter 2, "Executing Your Own Channel 
Programs (EXCP)" on page 63. 
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XDAP Requirements 



When using the XDAP macro instruction, you must, somewhere in your program, 
code a DCB macro instruction that produces a data control block (DCB) for the 
data set to be read or updated. You must also code an OPEN macro instruction 
that initializes the data control block and produces a data extent block (DEB). The 
OPEN macro instruction must be executed before any XDAP macro instructions 
are executed. 

When the XDAP macro instruction is assembled, a control block and executable 
code are generated. This control block may be logically divided into three sections: 

• An event control block (ECB) that is supplied with a completion code each 
time the direct access channel program is terminated. 

• An input/output block (lOB) that contains information about the direct access 
channel program. 

• A direct access channel program that consists of three or four channel 
command words (CCWs). The type of channel program generated depends on 
specifications in the parameters of the XDAP macro instruction. When 
executed, it locates a block by either its actual address or its key and reads, 
updates, or verifies the block. 

When the channel program has terminated, a completion code is placed into the 
event control block. After issuing XDAP, you should therefore issue a WATT 
macro instruction, specifying the address of the event control block, to regain 
control when the direct access program has terminated. If volume switching is 
necessary, you must issue an EOV macro instruction. When processing of the data 
set has been completed, you must issue a CLOSE macro instruction to restore the 
data control block. 



Macro Specifications for Use with XDAP 



When you are using the XDAP macro instruction, you must also code DCB, 
OPEN, CLOSE, WAIT, and, in some cases, the EOV macro instructions. The 
parameters of the XDAP macro instruction are listed and described here. For the 
other required macro instructions, special requirements or options are explained, 
but you should see "Macro Specifications for Use with EXCP" on page 73 for 
listings of their parameters. 



Defining a Data Control Block (DCB) 



You must issue a DCB macro instruction for each data set to be read, updated, or 
verified by the direct access channel program. To learn which macro instruction 
parameters to code, see "Defining Data Control Blocks for EXCP (DCB)" on 
page 73. 
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Initializing a Data Control Block (OPEN) 



The OPEN macro instruction initializes one or more data control blocks so that 
their associated data sets can be processed. You must issue OPEN for all data 
control blocks that are to be used by the direct access program. Some of the 
procedures performed when OPEN is executed are: 

• Construction of data extent block (DEB) 

• Transfer of information from DD statements and data set labels to the data 
control block 

• Verification or creation of standard labels 

• Loading of progranmier-written appendage routines 

The two parameters of the OPEN macro instruction are the address(es) of the data 
control block(s) to be initialized and the intended method of I/O processing of the 
data set. The method of processing may be specified as INPUT, OUTPUT, or 
EXTEND; however, if nothing is specified, INPUT is assumed. The parameters 
and different forms of the OPEN macro instruction are described in Data 
Administration: Macro Instruction Reference. 



Executing Direct Access Programs (XDAP) 



The XDAP macro instruction produces the XDAP control block (that is, the ECB, 
lOB, and channel program) and executes the direct access channel program. The 
format of the XDAP macro instruction is: 



\symbo1\ 


XDAP 


ecb-symbol 

^type 

fdcb-addr 

^area-addr 

^length-value 

M]key-addr,keylength-value)\ 

tblkref-addr 

,[sector-addr] 

l,MF-{E|Ln 



ecb-symbol — symbol or (2-12) 

the symbolic name to be assigned to the XDAP event control block. 
Registers can be used only with MF=E. 

OP^-{RI| RK I WI| WK I VI I VK} 

the type of I/O operation intended for the data set and the method by which 
blocks of the data set are to be located. One of the combinations shown 
must be coded in this field. 

The codes and their meanings are: 

R Read a block. 
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W Update a block. 

V Verify that the device is able to read the contents of a block, 

but do not transfer data. 

I Locate a block by identification. (The key portion, if present, 

and the data portion of the block are read, updated, or verified.) 

K Locate a block by key. (Only the data portion of the block is 

read, updated, or verified.) If you code this value, you must 
code the 'key-addr,keylength- value' operands. 

dcb-addr — A-type address or (2-12) 

the address of the data control block for the data set. If this data control 
block is also being used by a sequential access method (BSAM, BPAM, 
QSAM), you must reassemble the XDAP macro instruction. Otherwise, 
sequential access method appendages will be caUed at the conclusion of the 
XDAP channel program. 

area-addr — A-type address or (2-12) 

the address of an input or output area for a block of the data set. 

length-value — absexp or (2-12) 

the number of bytes to be transferred to or from the input or output area. If 
blocks are to be located by identification and the data set contains keys, the 
value must include the length of the key. The maximum number of bytes 
transferred is 32767. 

key-addr — RX-type address or (2-12) 

when blocks are to be located by key, the address of a virtual storage field 
that contains the key of the block to be read, updated, or verified. 

keylength-value — absexp or (2-12) 

when blocks are to be located by key, the length of the key. The maximum 
length is 255 bytes. 

blkref-addr — RX-type address or (2-12) 

the address of a field in virtual storage containing the actual track address of 
the track containing the block to be located. The actual address of a block is 
in the form MBBCCHHR, where M indicates which extent entry in the data 
extent block is associated with the direct access program; BB is not used, but 
must be zero; CC indicates the cylinder address; HH indicates the actual 
track address; and R indicates the block identification. R is not used when 
blocks are to be located by key. (For more detailed information, see 
"Converting a Relative Track Address to an Actual Track Address" on 
page 106.) 

sector-addr — RX-type address or (2-12) 

the address of a 1-byte field containing a sector value. The sector-address 
parameter is used for rotational position sensing (RPS) devices only. The 
parameter is optional, but its use will improve channel performance. When 
the parameter is coded, a set-sector CCW (using the sector value indicated 
by the data address field) precedes the search-ID-equal command in the 
channel program. The sector-address parameter is ignored if the type 
parameter is coded as RK, WK, or VK. If a sector address is specified in the 
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execute fonii of the macro, then a sector address, not necessarily the same, 
must be specified in the list form. The sector address in the executable form 
will be used. 

Note: No validity check is made on either the address or the sector value 
when the XDAP macro is issued. However, a unit check/command reject 
interruption will occur during channel-program execution if the sector value 
is invalid for the device or if the sector-addr operand is used when accessing 
a device without RPS. (For more detailed information, see "Obtaining 
Sector Nimiber of a Block on a Device with the RPS Feature" on page 108.) 

MF= 

you may use the L-form of the XDAP macro instruction for a macro 
expansion consisting of only a parameter list, or the E-form for a macro 
expansion consisting of only executable instructions. 

MF^E 

The first operand (ecb-symbol) is required and may be coded as a symbol or 
supplied in registers 2 through 12. The type, dcb-addr, area-addr, and 
length- value operands may be suppUed in either the L- or E-form. The 
blkref-addr operand may be suppUed in the E-form or moved into the 
lOBSEEK field of the lOB by you. The sector-addr is optional; it may be 
coded either in both the L- and E-form or in neither. 

MF=L 

The first two operands (ecb-symbol and type) are required and must be 
coded as symbols. If you choose to code length-value or keylength-value, 
they must be absolute expressions. Other operands, if coded, must be 
A-type addresses, (blkref-addr is ignored if coded.) 

Note: The XDAP macro biulds a channel program containing A-type addresses. 
These addresses refer to storage within the L-form of the macro. If you copy the 
L-form of the macro to a workarea so that the program may be reentrant, the 
E-form of the XDAP macro does not update the A-type addresses. This results in 
an invalid channel program. 

The dcb-addr, area-addr, blkref-addr, and sector-value operands may be coded as 
RX-type addresses or supplied in registers 2 through 12. The length- value and 
keylength-value operands can be specified as absolute expressions or decimal 
integers or supplied in registers 2 through 12. 
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End of Volume (EOV) 



The EOV macro instruction identifies end-of -volume and end-of -data-set 
conditions. For an end-of -volume condition, EOV causes switching of volumes 
and verification or creation of standard labels. For an end-of -data-set condition, 
EOV causes your end-of-data-set routine to be entered. When using XDAP, you 
issue EOV if switching of direct access volumes is necessary or if secondary 
allocation is to be performed for a direct access data set opened for output. 

For details about the parameters of the EOV macro instruction, see "End of 
Volume (EOV)" on page 81. 



Restoring a Data Control Block (CLOSE) 



The CLOSE macro instruction restores one or more data control blocks so that 
processing of their associated data sets can be terminated. You must issue CLOSE 
for all data sets that were used by the direct access channel program. Some of the 
procedures performed when CLOSE is executed are: 

• Release of data extent block (DEB) 

• Removal of information transferred to data control block fields when OPEN 
was executed 

• Verification or creation of standard labels 

• Release of programmer-written appendage routines 

The CLOSE macro instruction must identify the address of at least one data 
control block to be restored, and may specify other parameters. The parameters 
and different forms of the CLOSE macro instruction are described in Da/a 
Administration: Macro Instruction Reference. 



Control Blocks Used with XDAP 



The three control blocks generated during execution of the XDAP macro 
instruction are described here. 



Event Control Block (ECB) 



The event control block (ECB) begins on a fullword boundary and occupies the 
first 4 bytes of the XDAP control block. Each time the direct access channel 
program terminates, the I/O supervisor places a completion code containing status 
information into the event control block (Figure 23 on page 105). Before 
examining this information, you must wait for the completion of the channel 
program by issuing a WATT macro instruction that specifies the address of the 
event control block. 
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Input/Output Block (lOB) 



The input/output block (lOB) is 40 bytes in length and immediately follows the 
event control block. "Control Block Fields" on page 88 contains a diagram of the 
input/output block (Figure 23 on page 105). You may want to examine the 
lOBSENSO, lOBSENSl, and lOBCSW fields if the ECB is posted with X'41'. 



WAIT bit 


COMPLETE bit 


Completion code 



bit 




1 



31 



Wait bit 

A one bit in this position indicates that the direct access channel program has not 
been completed. 

Complete bit 

A one bit in this position indicates that the channel program has been completed; 
if it has not been completed, a zero bit is In this position. 

Completion code 

This code, including the wait and complete bits, may be one of the following 4-byte 
hexadecimal expressions: 

CODE MEANING 

7F000000 Direct access program has terminated without error. 

41000000 Direct access program has terminated with permanent error. 

42000000 Direct access program has terminated because a direct access extent 
address has been violated. 

4F000000 Error recovery routines have been entered because of direct access error 
but are unable to read home address or record 0. 

Figure 23. Event Control Block (ECB) after Posting of Completion Code (XDAP) 



Direct Access Channel Program 



The direct access channel program is 24 bytes in length (except when set sector is 
used for RPS devices) and immediately foUows the input/output block. Depending 
on the t5rpe of I/O operation specified in the XDAP macro instruction, one of four 
channel programs may be generated. The three channel command words for each 
of the four possible channel programs are shown in Figure 24 on page 106. 

When a sector address is specified with an RI, VI, or WI operation, the channel 
program is 32 bytes in length. Each of these channel programs in Figure 24 on 
page 106 would be, in this case, preceded by a set sector command. 
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Converting a Relative Track Address to an Actual Track Address 



To issue XDAP, you must provide the actual track address of the track containing 
the block to be processed. If you know only the relative track address, you can 
convert it to the actual address by using a resident system routine. The entry point 
to this conversion routine is labeled lECPCNVT. The address of the entry point 
(CVTPCNVT) is in the communication vector table (CVT). The address of the 
CVT is m location 16. 



Type of I/O Operation 


ccw 


Command Code 


Read by identification 
Verify by identification^ 


1 

2 

3 


Search ID Equal 
Transfer in Channel 
Read Key and Data 


Read by key 
Verify by key^ 


1 
2 
3 


Search Key Equal 
Transfer in Channel 
Read Data 


Write by identification 


1 
2 
3 


Search ID Equal 
Transfer in Channel 
Write Key and Data 


Write by key 


1 
2 
3 


Search Key Equal 
Transfer in Channel 
Write Data 



For verifying operations, the third CCW is flagged to 
suppress the transfer of information to virtual storage. 

Figure 24. The XDAP Channel Programs 



The conversion routine does all its work in general registers. You must load 
registers 0, 1, 2, 14, and 15 with input to the routine. Register usage is as follows: 



Register Use 



Must be loaded with a 4-byte value of the form TTRN, where TT is 
the track number relative to the beginning of the data set, R is the the 
block identification on that track, and N is the concatenation number 
of a BPAM data set. (0 indicates the first data set in the 
concatenation, an nonconcatenated BPAM data set, or a non-BPAM 
data set.) 

Must be loaded with the address of the data extent block (DEB) of the 
data set. 

Must be loaded with the address of an 8-byte area that is to receive 
the actual address of the block to be processed. The converted 
address is of the form MBBCCHHR, where M indicates which extent 
entry in the data extent block is associated with the direct access 
program (0 indicates the first extent, 1 indicates the second, and so 
forth); BB is two bytes of zeros; CC is the cylinder address; HH is the 
actual track address; and R is the block number. 
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3-8 Are not used by the conversion routine. 

9-13 Are used by the conversion routine and are not restored. 

14 Must be loaded with the address to which control is to be returned 
after execution of the conversion routine. 

15 Is used by the conversion routine as a base register and must be loaded 
with the address where the conversion routine is to receive control. 



Return Codes from the Conversion Routine 



When control is returned to your program, register 15 will contain one of the 
following return codes: 



Code Meaning 

O(X'OO') Successful conversion. 

4(X'04') The relative block address converts to an actual track address outside 
the extents defined in the DEB. 



Converting an Actual Track Address to a Relative Track Address 



To get the relative track address when you know the actual track address, you can 
use the conversion routine labeled lECPRLTV. The address of the entry point 
(CVTPRLTV) is in the communication vector table (CVT). The address of the 
CVT is m location 16. 

The conversion routine does all its work in general registers. You must load 
registers 1, 2, 14, and 15 with input to the routine. Register usage is as follows: 

R^jster Use 

Will be loaded with the resulting TTRO to be passed back to the caller. 

1 Must be loaded with the address of the data extent block (DEB) of the 
data set. 

2 Must be loaded with the address of an 8-byte area containing the 
actual address to be converted to a TTR. The actual address is of the 
form MBBCCHHR. 

3-8 Are not used by the conversion routine. 

9-13 Are used by the conversion routine and are not restored. 
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14 Must be loaded with the address to which control is to be returned 
after execution of the conversion routine. 

15 Is used by the conversion routine as a base register and must be loaded 
with the address where the conversion routine is to receive control. 



Obtaining Sector Number of a Block on a Device with the RPS Feature 

To obtain the performance improvement given by rotational position sensing, you 
should specify the sector-addr parameter in the XDAP macro. For programs that 
can be used with both RPS and non-RPS devices, the UCBRPS bit (bit 3 at an 
offset of 17 bytes into the UCB) should be tested to determine whether the device 
has rotational position sensing. If the UCBRPS bit is off, a channel program with a 
"set sector" command must not be issued to the device. 

The sector-addr parameter on the XDAP macro specifies the address of a 1-byte 
field in your region. You must store the sector number of the block to be located 
in this field. You can obtain the sector number of the block by using a resident 
conversion routine, lECOSCRl. The address of this routine is in field CVTOSCRl 
of the CVT, and the address of the CVT is in location 16. The routine should be 
invoked via a BALR 14,15 instruction. If you are passing the track balance to the 
routine, invoke the routine using a BAL 14,8(15). If you are computing the sector 
value on modulo devices (3375 and 3380) with variable length records, you must 
pass the track balance to the sector convert routine. 

For RPS devices, the conversion routine does aU its work in general registers. You 
must load registers 0, 2, 14, and 15 with input to the routine. Register usage is as 
follows: 
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Register Use 

For fixed, standard blocks or fixed, unblocked records not in a 
partitioned data set: Register must be loaded with a 4-byte value in 
the form XXKR, where XX is a 2-byte field containing the physical 
block size, K is a 1-byte field containing the key length, and R is a 
1-byte field containing the number of the record for which a sector 
value is desired. The high-order bit of register must be turned off 
(set to 0) to indicate fixed-length records. 

Passing the track balance: Register must be loaded with the 4-byte 
value of the track balance of the record preceding the required record. 

For all other cases: Register must be loaded with a 4-byte value in 
the form BBIR, where BB is the total number of key and data bj^es on 
the track up to, but not including, the target record; I is a 1-byte key 
indicator (1 for keyed records, for records without keys); and R is a 
1-byte field containing the number of the record for which a sector 
value is desired. The high-order bit of register must be turned on 
(set to 1) to indicate variable-length records. 

1 Not used by the sector-convert routine. 

2 Must be loaded with a 4-byte field where the first byte is the UCB 
device type code for the device (obtainable from UCB +19), and the 
remaining three bytes are the address of a 1-byte area that is to 
receive the sector value. 

3-8 Not used. 

9-11 Used by the convert routine and are not saved or restored. 

12,13 Not used. 

14 Must be loaded with the address in which control is to be returned 
after execution of the sector conversion routine, 

15 Used by the conversion routine as a base register and must be loaded 
with the address of the entry point to the conversion routine. 
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Chapter 4. Password Protecting Data Sets 



The password protection described in this chapter does not apply to VSAM data 
sets. Information about VSAM data set protection is in VSAM Administration: 
Macro Instruction Reference and Access Method Services Reference. (For 
information on RACF and its relationship to password protection, see RACF 
General Information.) To use the data set protection feature of the operating 
system, you must create and maintain a PASSWORD data set consisting of records 
that associate the names of the protected data sets with the password assigned to 
each data set. There are four ways to maintain the PASSWORD data set: 

• You can write your own routines. 

• You can use the PROTECT macro instruction. 

• You can use the utility control statements of the lEHPROGM utility program. 

• If you have TSO, you can use the TSO PROTECT command. 

This chapter discusses only the first two of the four ways: It provides technical 
detail about the PASSWORD data set that is necessary for writing your own 
routines, and it describes how to use the PROTECT macro instruction. (The last 
two of the four ways are discussed in other publications, as indicated in the list of 
publications below.) 

Before using the information in this chapter, you should be familiar with 
information in several related publications. The following publications are 
recommended: 

• Data Administration Guide contains a general description of the data set 
protection feature. 

• System Messages contains a description of the operator messages and replies 
associated with the data set protection feature. 

• JCL Reference contains a description of the data definition (DD) statement 
parameter used to indicate that a data set is to be password protected. 

• Utilities contains a description of how to maintain the PASSWORD data set 
using the utility control statements of the lEHPROGM utility program. 

• TSO Command Language Reference describes the use of the TSO PROTECT 
command. 
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Providing Data Set Security 



In addition to the usual label protection that prevents the opening of a data set 
without the correct data set name, the operating system provides data set security 
options that prevent unauthorized access to confidential data. Password protection 
prevents access to data sets untU a correct password is entered by the system 
operator, or, for TSO, by a remote terminal operator. 

The following are the types of access allowed to password-protected data sets: 

• PWREAD/PWWRITE — A password is required for read or write. 

• PWREAD/NOWRTTE — A password is required for read. Writing is not 
allowed. 

• NOPWREAD/PWWRITE — ^Readmg is allowed without a password. A 
password is required to write. 

To prepare for use of the data set protection feature of the operating system, you 
place a sequential data set, named PASSWORD, on the system residence volume. 
This data set must contain at least one record for each data set placed under 
protection. In turn, each record contains a data set name, a password for that data 
set, a counter field, a protection mode indicator, and a field for recording any 
information you desire to log. On the system residence volume, these records are 
formatted as a "key area" (data set name and password) and a "data area" 
(counter field, protection mode indicator, and logging field). The data set is 
searched on the "key area." 

Note: The area allocated to the data set should not have been previously used for 
a PASSWORD data set, as this may cause unpredictable results when adding 
records to the data set. 

You can write routines to create and maintain the PASSWORD data set. If you 
use the PROTECT macro instruction to maintain the PASSWORD data set, see 
"Maintaining the PASSWORD Data Set (PROTECT Macro)" on page 116. If 
you use the lEHPROGM utility program to maintain the PASSWORD data set, see 
Utilities. These routines may be placed in your own library or in the system's 
library (SYSl.LINKLIB). You may use a data management access method or 
EXCP programming to read from and write to the PASSWORD data set. 

If a data set is to be placed under protection, it must have a protection indicator set 
in its label (format- 1 DSCB or header 1 tape label). This is done by the operating 
system when the data set is created, by the lEHPROGM utility program, or by the 
PROTECT macro when creating or adding the control password. The protection 
indicator is set in response to a value in the LABEL= operand of the DD statement 
associated with the data set being placed under protection. JCL Reference describes 
the LABEL operand. 

Note: Data sets on magnetic tape are protected only when standard labels are 
used. 

Password-protected data sets can only be accessed by programs that can supply the 
correct password. When the operating system receives a request to open a 
protected data set, it first checks to see whether the data set has already been 
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opened for this job step. If so, only the access mode will be checked to determine 
whether it is compatible with the protection mode under which it was previously 
opened. If the data set has not been previously opened by this job step or if the 
access mode is not compatible with the protection mode under which it was 
previously opened, a message is issued that asks for the password; the message 
goes to the operator console. If the program requesting that the data set be opened 
is running under TSO in the foreground, the message goes to the TSO terminal 
operator. If you want the password supplied by another method in your 
installation, you can modify the READPSWD source module or code a new routine 
to replace READPSWD in SYSl.LPALIB. 



PASSWORD Data Set Characteristics 



The PASSWORD data set must reside on the same volume as your operating 
system. The space you allocate to the PASSWORD data set must be contiguous, 
that is, its DSCB must indicate only one extent. The amount of space you allocate 
depends on the number of data sets your installation wants to protect. Each entry 
in the PASSWORD data set requires 132 bytes of space. The organization of the 
PASSWORD data set is physical-sequential; the record format is unblocked, 
fixed-length records (RECFM=F). Each record that forms the data area is 80 
bytes long (LRECL=80,BLKSIZE=80) and is preceded by a 52-byte key 
(KEYLEN=52). The key area contains the fully qualified data set name of as 
many as 44 bytes and a password of one to eight bytes, left justified with blanks 
added to fill the areas. The password assigned may be from one to eight 
alphameric characters in length. 

Note: For data sets on magnetic tape designed according to the specifications of 
the International Organization for Standardization (ISO) 1001-1979, the 
equivalent American National Standards Institute (ANSI) X3.27-1978, or the 
Federal Information Processing Standards (FIPS) 79, do not include generation 
and version numbers as part of generation data set names. The generation and 
version numbers are not included as part of the names in the tape labels and are 
ignored if included in the PASSWORD data set. 

You can protect the PASSWORD data set itself by creating a password record for 
it when your program initially builds the data set. Thereafter, the PASSWORD 
data set cannot be opened (except by the operating system routines that scan the 
data set) unless the operator enters the password. 

Note: If a problem occurs on a password-protected system data set, maintenance 
personnel must be provided with the password in order to access the data set and 
resolve the problem. 



Creating Protected Data Sets 



A data definition (DD) statement parameter (LABEL=) may be used to indicate 
that a data set is to be password protected. For data sets on DASD, an alternative 
method is to use the PROTECT macro instruction for a previously allocated data 
set. A data set may be created and the protection indicator set in its label without 
entering a password record for it in the PASSWORD data set. 

Operating procedures at your installation must ensure that password records for all 
data sets currently password-protected are entered in the PASSWORD data set. 
Installations where independent computing systems share common DASD 
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resources must ensure that PASSWORD data sets on all systems contain the 
appropriate password records for any protected data set on shared DASD. 

Under certain circumstances, the order in which data sets are allocated and 
unallocated from multiple systems on shared DASD may result in loss of password 
protection. For example, if an unprotected data set is allocated and opened by a 
user on System A and then scratched by a different user on System B, the first user 
is given a "window" to the unallocated (free) area. If any data set, protected or 
unprotected, is allocated in that space by a user on either system during the time 
the "window" is open, the new data set has no protection from the user with the 
"window." 

While the allocation disposition is still NEW, a password-protected data set can be 
used without supplying a password. However, once the data set is unallocated, any 
subsequent attempt to open will result in termination of the program unless the 
password record is available and the correct password is supplied. Note that, if the 
protection mode is NOPWREAD and the request is to open the data set for input 
or read backward, no password will be required. 



Tape Volumes Containing More Than One Password-Protected Data Set 



To password protect a data set on a tape volume containing other data sets, you 
must password protect all the data sets on the volume. (Standard labels — SL, SUL, 
AL, or AUL — are required. For definitions of these label t3rpes and the 
protection-mode indicators that can be used, see Magnetic Tape Labels and File 
Structure Administration.) 

If you issue an OPEN macro instruction to create a data set following an existing, 
password-protected data set, the password of the existing data set will be verified 
during open processing for the new data set. The password supplied must be 
associated with a PWWRITE protection-mode indicator. 



Protection Feature Operating Characteristics 



Termination of Processing 



The topics that follow provide information concerning actions of the protection 
feature in relation to termination of processing, volume switching, data set 
concatenation, SCRATCH and RENAME functions, and counter maintenance. 



Processing is terminated when: 

1. The operator cannot supply the correct password for the protected data set 
being opened after two tries. 

2. A password record does not exist in the PASSWORD data set for the protected 
data set being opened. 

3. The protection-mode indicator in the password record and the method of I/O 
processing specified in the Open routine do not agree, for example, OUTPUT 
specified against a read-only protection-mode indicator. 

4. There is a mismatch in data set names for a data set involved in a volume 
switching operation. This is discussed in the next paragraph. 
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Volume Switching 



Data Set Concatenation 



The system ensures a continuation of password protection when volumes of a 
multivolume data set are switched. It accepts a newly-mounted tape volume to be 
used for input or a newly-mounted direct access volume, regardless of its use, if 
these conditions are met: 

• The data set name in the password record for the data set is the same as the 
data set name in the JFCB. (This ensures that the problem program has not 
changed the data set name in the JFCB since the data set was opened.) 

• The protection-mode indicator in the password record is compatible with the 
processing mode, and a valid password has been supplied. 

The system accepts a newly-mounted tape volume to be used for output under any 
of these conditions: 

• The security indicator in the HDRl label indicates password protection; the 
data set name in the password record is the same as the data set name in the 
JFCB; and the protection-mode indicator is compatible with the processing 
mode. (If the data set name in the JFCB has been changed, a new password is 
requested from the operator.) 

• The security indicator in the HDRl label does not indicate password 
protection. (A new label will be written with the security indicator indicating 
password protection.) 

• Only a volume label exists. (A HDRl label will be written with the security 
indicator indicating password protection.) 



A password is requested for every protected data set that is involved in a 
concatenation of data sets, regardless of whether the other data sets involved are 
protected or not. 



SCRATCH and RENAME Functions 



Counter Maintenance 



To delete or rename a protected data set, it is necessary that the job step making 
the request be able to supply the password. The system first checks to see if the 
job step is currently authorized to write to the data set. If not, message IEC301 A 
is issued to request the password. The password provided must be associated with 
a "WRITE" protection-mode indicator. 



The operating system increments the counter in the password record on each usage, 
but no overflow indication will be given (overflow after 65535 openings). You 
must provide a counter maintenance routine to check and, if necessary, reset this 
counter. 
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Maintaining the PASSWORD Data Set (PROTECT Macro) 

To use the PROTECT macro instruction, your PASSWORD data set must be on 
he system residence volume. The PROTECT macro can be used to: 

Add an entry to the PASSWORD data set. 

Replace an entry in the PASSWORD data set. 

Delete an entry from the PASSWORD data set. 

Provide a list of information about an entry in the PASSWORD data set; this 
list will contain the security counter, access type, and the 77 bytes of security 
information in the "data area" of the entry. 

In addition, the PROTECT macro updates the DSCB of a protected direct access 
data set to reflect its protection status; this feature eliminates the need for you to 
use job control language when you protect a data set. 

PASSWORD Data Set Characteristics and Record Format (With PROTECT macro) 

When you use the PROTECT macro, the record format and characteristics of the 
PASSWORD data set are no different from the record format and characteristics 
that apply when you use your own routines to maintain it. 

Number of Records for Each I^otected Data Set 

When you use the PROTECT macro, the PASSWORD data set must contain at 
least one record for each protected data set. The password (the last 8 bytes of the 
"key area") that you assign when you protect the data set for the first time is called 
the control password. In addition, you may create as many secondary records for 
the same protected data set as you need. The passwords assigned to these 
additional records are called secondary passwords. This feature is helpful if you 
want several users to have access to the same protected data set, but you also want 
to control the way they can use it. For example: One user could be assigned a 
password that allowed the data set to be read and written, and another user could 
be assigned a password that allowed the data set to be read only. 

Note: The PROTECT macro will update the protection-mode indicator in the 
format- 1 DSCB in the protected data set only when you issue it for adding, 
replacing, or deleting a control password. 



Protection-Mode Indicator 



You can set the protection-mode indicator (third data byte) in the password record 
to one of four different values: 

• X'OO' to indicate that the password is a secondary password and the protected 
data set is to be read only (PWREAD). 

• X'80' to indicate that the password is the control password and the protected 
data set is to be read only (PWREAD). 
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• X'Ol ' to indicate that the password is a secondary password and the protected 
data set is to be read and written (PWREAD/PW WRITE). 

• X'81 ' to indicate that the password is the control password and the protected 
data set is to be read and written (PWREAD/PWWRITE). 

Because of the sequence in which the protection status of a data set is checked, the 
following defaults will occur: 

If control password is; Secondary password must be: 

1 . PWREAD/PWWRITE or PWREAD/PWWRITE or 
PWREAD/NOWRITE PWREAD/NOWRITE 

2 . NOPWREAD/PWWRITE NOPWREAD/PWWRITE 

If the control password is set to either of the settings in item 1 above, the 
secondary password will be set to PWREAD/PWWRITE if you try to set it to 
NOPWREAD/PWWRITE. 

If the control password is changed from either of the settings in item 1 to the 
setting in item 2 above, the secondary password will be automatically reset to 
NOPWREAD/PWWRITE. 

If the control password is changed from the setting in item 2 to either of the 
settings in item 1 above, the secondary password is set by the system to 
PWREAD/PWWRITE. 

Because the DSCB of the protected data set is updated only when the control 
password is changed, you may request protection attributes for secondary 
passwords that conflict with the protection attributes of the control password. 



PROTECT Macro Syntax 

The format is: 



[symbol] 


PROTECT 


parameter list address 



parameter list address — A-type address, (2-12), or (1) 

indicates the location of the parameter list. The parameter list must be set up 
before the PROTECT macro is issued. The address of the parameter list 
may be passed in register 1, in any of registers 2 through 12, or as an A-type 
address. The first byte of the parameter list must be used to identify the 
function (add, replace, delete, or Ust) you want to perform. See Figure 25 
on page 118 through Figure 28 on page 123 for the parameter lists and 
codes used to identify the functions. 

Note: The parameter lists and the areas addressed by the list must reside below 16 
megabytes virtual. 
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PROTECT Macro Parameter Lists 



x'or 


13 Control password pointer 


1 00 00 00 


16 Number of volumes 


4 Data set name length 


17 Volume 1 1st pointer 


5 Data set name pointer 


20 Protection code 


8 00 


21 New password pointer 


9 00 00 00 


2k String length 


12 00 


25 Str ing pointer 



Notes: 

OX'Ol' 

Entry code indicating ADD function. 

4 Data set name length. 



5 Data set name pointer. 



13 Control password pointer. 

The control password is the password assigned when the data set was placed under protection for the 
first time. The pointer can be 3 bytes of binary zeros if the new password is the control password. 

16 Number of volmnes. 

If the data set is not cataloged and you want to have it flagged as protected, you must specify the 
number of volumes in this field. A zero indicates that the catalog information should be used. 

17 Volume list pointer. 

If the data set is not cataloged and you want to have it flagged as protected, you provide the address of a 
list of volume serial numbers in this field. Zeros indicate that the catalog information should be used. 

20 Protection code. 

A one-byte number indicating the type of protection: X'OO* indicates default protection (for the ADD 
function; the default protection is the type of protection specified in the control password record of the 
data set); X'OI' indicates that the data set is to be read and written; X'02' indicates that the data set is 
to be read only; and X'03' indicates that the data set can be read without a password, but a password is 
needed to write into it. The PROTECT macro will use the protection code value, specified in the 
parameter list, to set the protection-mode indicator in the password record. 

Figure 25 (Part 1 of 2). Parameter List for ADD Function 
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21 New password pointer. 

If the data set is being placed under protection for the first time, the new password becomes the control 
password. If you are adding a secondary entry, the new password is different from the control password. 

24 String length. 

The length of the character string (maximum 77 bytes) that you want to place in the optional 
information field of the password record. If you don't want to add information, set this field to zero. 

25 String pointer. 

The address of the character string that is going to be put in the optional information field. If you don't 
want to add additional information, set this field to zero. 

Figure 25 (Part 2 of 2). Parameter List for ADD Function 
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X'02' 


13 


Control password pointer 


1 00 00 00 


16 


Number of volumes 


k 


Data set name length 


17 


Volume list pointer 


5 


Data set name pointer 


20 


Protection code 


8 


00 


21 


New password pointer 


9 


Current password pointer 


2k 


String length 


12 


00 


25 


String pointer 



Notes: 

0X'02'. 

Entry code indicating REPLACE function. 

4 Data set name length. 



5 Data set name pointer. 



9 Pointer to current password. 

The address of the password that is going to be replaced. 

13 Control password pointer. 

The address of the password assigned to the data set when it was first placed under protection. The 
pointer can be set to 3 bjrtes of binary zeros if the current password is the control password. 

16 Number of volumes. 

If the data set is not cataloged and you want to have it flagged as protected, you have to specify the 
number of volumes in this field. A zero indicates that the catalog information should be used. 

17 Volume list pointer. 

If the data set is not cataloged and you want to have it flagged as protected, you have to provide the 
address of a list of volume serial numbers in this field. If this field is zero, the catalog information will be 
used. 

20 Protection code. 

A one-byte number indicating the type of protection: X'OO' indicates that the protection is default 
protection (for the REPLACE function the default protection is the protection specified in the current 
password record of the data set); X'Ol ' indicates that the data set is to be read and written; X'02* 
indicates that the data set is to be read only; and X' 03 'indicates that the data set can be read without a 
password, but a password is needed to write into the data set. 

Figure 26 (Part 1 of 2). Parameter List for REPLACE Function 
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21 New password pointer. 

The address of the password that you want to replace the current password. 

24 String length. 

The length of the character string (maximiun 77 bytes) that you want to place in the optional information 
Held of the password record. Set this fleld to zero if you don't want to add additional information. 

25 String pointer. 

The address of the character string that is going to be put in the optional information field of the password 
record. Set the address to zero if you don't want to add additional information. 

Figure 26 (Part 2 of 2). Parameter List for REPLACE Function 
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X'03' 


9 


Current password pointer 


1 


00 00 00 


12 


00 


k 


Data set name length 


13 


Control password pointer 


5 


Data set name pointer 


16 


Number of volumes 


8 


00 


17 


Volume 1 ist pointer 



Notes: 

0X03'. 

Entry code indicating DELETE function. 

4 Data set name length. 



5 Data set name pointer. 



9 Current password pointer. 

The address of tlie password that you want to delete. You can delete either a control entry or a 
secondary entry. 

13 Control password pointer. 

The address of the password assigned to the data set when it was placed under protection for the first 
time. The pointer can be 2 bytes of binary zeros if the current password is also the control password. 

16 Number of volumes. 

If the data set is not cataloged and you want to have it flagged as protected, you must specify the 
number of volumes in this field. A zero indicates that the catalog information should be used. 

17 Volume list pointer. 

If the data set is not cataloged and you want to have it flagged as protected, you must provide the 
address of a list of volume serial numbers in this field. If this field is zero, the catalog information will be 
used. 

Figure 27. Parameter List for DELETE Function 
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X'OA' 


5 


Data set name pointer 


1 


80-byte buffer pointer 


8 


00 


k 


Data set name length 


9 


Current password pointer 



Notes: 

0X'04'. 

Entry code indicating LIST function. 

1 80-byte buffer pointer. 

The address of a buffer where the list of information can be returned to your program by the macro 
instruction. 

4 Data set name length. 



5 Data set name pointer. 



9 Current password pointer. 

The address of the password of the record that you want listed. 

F^ure 28. Parameter List for LIST Function 
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Return Codes from the PROTECT Macro 



When the PROTECT macro finishes processing, register IS contains one of the 
following return codes: 



Code Meaning 

O(X'OO') The updating of the PASSWORD data set was successfully 
completed. 

4(X*04' ) The PASSWORD of the data set name was akeady in the password 
data set. 

8(X' 08 • ) The password of the data set name was not m the PASSWORD 
data set. 

12(X'0C ' ) A control password is required or the one supplied is incorrect. 

16(X* 10' ) The supplied parameter list was incomplete or incorrect. 

20(X' 14' ) There was an I/O error in the PASSWORD data set. 

24(X'18»)» The PASSWORD data set was fuU. 

28(X' 1 C • ) The validity check of the buffer address failed. 

32(X'20')2 The LOCATE macro failed. LOCATE's return code is in register 1, 
and the number of indexes searched is in register 0. 

36(X' 24 • )2 The OBTAIN macro failed. OBTAIN's return code is in register 1 . 

40(X'28')2 The DSCB could not be updated. 

44(X' 2C » ) The PASSWORD data set does not exist. 

48 (X' 30 • )2 Tape data set cannot be protected. 

52(X'32')2 Data set in use. 

56(X'38')2 The data set uses the virtual storage access method (VSAM). 



Notes: 



For this return code, a message is written to the console indicating that 
the PASSWORD data set is full. 

For this return code, the PASSWORD data set has been updated, but 
the DSCB has not been flagged to indicate the protected status of the 
data set. 
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Chapters. Exit Routines 



The detailed information about installation-written exit modules has been moved to 
Data Facility Product: Customization. 

This chapter discussed how exit modules can: 

• Take control before and after direct access device storage management 
(DADSM) processing 

• Take control during Open for a DCB 

• Determine whether a missing data set control block (such as for a data set that 
has been moved to another volume) can be restored to a volume 

• Recover from errors that may occur during the opening, closing, or handling of 
an end-of -volume condition for a data set associated with the user's task 

• Bypass, limit, or override system-calculated values that assist you in selecting 
optimum DASD data set block size/ CI size. 
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Chapter 6. System Macro Instructions 



Introduction 



This chapter describes miscellaneous macro instructions that allow you to: 

Modify control blocks (RDJFCB macro) 

Obtain information from control blocks and system tables (DEVTYPE macro) 

Perform track capacity calculations (TRKCALC macro) 

Allocate a data set based on a partial DSCB (REALLOC macro) 

Load a message display on an IBM 3480 Magnetic Tape Subsystem 
(MSGDISP macro) 

Before reading this chapter, you should be familiar with the following publication: 

• Assembler H Version 2 Application Programming: Guide contains the 
information necessary to code programs in the assembler language. 



The system macro instructions are described in these functional groupings: 

Mapping (ffiFUCBOB, lEFJFCBN, and CVT) 

Obtaining device characteristics (DEVTYPE) 

Manipulating the JFCB (RDJFCB) 

Data security (DEBCHK) 

Manipulating queues (PURGE and RESTORE) 

Performing track capacity calculations (TRKCALC) 

Allocatmg a DASD data set (REALLOC) 

Releasing unused space from a DASD data set (PARTREL) 

Loading a message display on an IBM 3480 Magnetic Tape Subsystem 
(MSGDISP) 
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Mapping System Data Areas 



The lEFUCBOB, ffiFJFCBN, and CVT macro instructions are used as DSECT 
expansions that define the symbolic names of fields within the unit control block 
(UCB), job file control block (JFCB), and communication vector table (CVT), 
respectively. 

The CVT, ffiFUCBOB, and lEFJFCBN macro defmitions are in a distribution 
library named SYSl.AMODGEN. Before you can issue the macros, you must copy 
them from SYSl.AMODGEN into SYSl.MACLBB (the lEBCOPY utility can be 
used to copy the macros), or SYSl.AMODGEN may be concatenated to the macro 
library before reference is made to SYSl.AMODGEN. 



lEFUCBOB— Mapping the UCB 



This macro instruction defines the symbolic names of the fields in the unit control 
block (UCB). The macro does not include a DSECT statement. However, if you 
specify PREFIX=YES, the DSECT statement is provided. 

The format is: 



[symboll 


lEFUCBOB 


lLIST=|NO|YESn 
[,PREFlX=^NO|YES}J 



LIST={NO|YES} 
NO 



specifies that only the UCB prolog is to be printed. 



YES 



specifies that the UCB prolog and the rest of the UCB are to be 
printed. 



PREFIX=|NO|YESJ 
NO 



YES 



lEFJFCBN— Mapping the JFCB 



specifies that no prefix is to be printed. 



specifies that the prefix and main body of the UCB are to be printed. 
A DSECT statement is included if you specify PREFIX=YES. 



This macro instruction defines the symbolic names of the fields in the job file 
control block (JFCB). The macro does not include a DSECT statement. If you 
require one, code a DSECT statement before the macro statement. 
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The format is: 



[symboll 


lEFJFCBN 


ILIST=eiO|YESn 



LIST=(NO|YES} 

NO 

specifies that only the JFCB prolog is to be printed. 

YES 

specifies that the JFCB prolog and the rest of the JFCB are to be 
printed. 



CVT— Mapping the CVT 



This macro instruction defines the symbolic names of all fields in the 
communication vector table (CVT). 

The format is: 



[symbol] 


CVT 


lDSECT={NO|YESn 
[,LIST=|NO|YES}l 



DSECT=eiQ|YES} 

NO 

specifies that you do not want a DSECT. 

YES 

specifies that you want a DSECT. 

LIST«{NO|YES} 

NO 

specifies that only the CVT prolog is to be printed. 

YES 

specifies that the CVT prolog and the rest of the CVT are to be 
printed. 



Obtaining I/O Device Characteristics 



Use the DEVTYPE macro instruction to request information relating to the 
characteristics of an I/O device, and to cause this information to be placed into a 
specified area. (The results of a DEVTYPE macro instruction executed before a 
checkpoint is taken should not be considered vaUd after a checkpoint/restart 
occurs.) The EHADVA macro maps the data returned by the DEVTYPE macro. 

The topics that follow discuss the DEVTYPE macro, device characteristics, and 
particular output for particular devices. 
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DEVTYPE Macro Specification 

The format is: 



[symbol\ 


DEVTYPE 


ddloc-addrx 
fOrea-addrx 
[,DEVTAB1 
[,RPS1 



For the UCBLIST function, the fonnat is: 



[symboll 


DEVTYPE 


(area-addrx,area-size) 
,VCBLlSi =(ucbl-addr,ucbl-num) 



ddloc-addrx 

the name of an 8-byte field that contains the sjrmbolic name of the DD 
statement to which the device is assigned. The name must be left justified in 
the 8-byte field, and must be followed by blanks if the name is fewer than 
eight characters. The doubleword need not be on a doubleword boundary. 

area-addrx 

the name of an area into which the device information is to be placed. If your 
program does not specify the UCBLIST function, the area can be two, five, 
or six fullwords long, depending on whether or not you specify the DEVTAB 
and RPS operands. If your program specifies the UCBLIST function, the 
area must be 6 fullwords long. The area must be on a fullword boundary. 

area-size 



the size of the area into which the device information is to be placed. 

DEVTAB 

This operand is only required for direct access devices. If DEVTAB is 
specified, the following number of words of information is placed in your 
area: 

• For direct access devices: 5 words 

• For non-direct access devices: 2 words 

If you do not code DEVTAB, one word of information is placed in your area 
if the reference is to a graphics or teleprocessing device; for any other type 
of device, two words of information are placed in your area. 

RPS 

If RPS is specified, DEVTAB must also be specified. The RPS parameter 
causes one additional full word of RPS information to be included with the 
DEVTAB information. 

UCBLIST 

UCBLIST provides a list service in which the caller passes a list and count of 
the addresses of UCBs. The information returned is always given in 6-word 
entries (one entry per UCB address) regardless of the device type. The 
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words that would contain information not applicable to the device for that 
entry are not altered. 

Note: Any reference for a DUMMY data set in the DEVTYPE macro instruction 
will cause eight bytes of zeros to be placed in the output area. Any reference to a 
SYSIN or SYSOUT data set causes X' 00000102' to be placed in word and 
32760 (X'00007FF8') to be placed in word 1 in the output area. Any reference 
to a file allocated to a TSO terminal causes X' 000001 01 ' to be placed in word 
and 32760 (X'00007FF8') to be placed in word 1 in the output area. 



Device Characteristics Information 



The following information is placed into your area as a result of issuing a 
DEVTYPE macro: 

WordO 

Describes the device as defined in the UCBTYP field of the UCB. 

Word 1 

Maximum block size. For direct access devices, this value is the smaller of 
either the maximum size of a nonkeyed block or the maximum block size 
allowed by the operating system; for magnetic tape devices, this value is the 
maximum block size allowed by the operating system. For all other devices, 
this value is the maximum block size accepted by the device. 

If your program specifies either DEVTAB or UCBLIST, the next three fullwords 
contain the following information about direct access devices: 



Word 2 



Bytes 0-1 The number of physical cyUnders on the device, including 

alternates. 

Bytes 2-3 The number of tracks per cylinder. 

Note: Before you use bytes 2 and 3, read the description of 
word 4, hyXt 1 , bit 0. 

Words 

Bytes 0-1 Maximum track length. Note that for the IBM 3375 and 

3380 direct access devices, this value is not equal to the value 
in word 1 (maximum block size) as it is for other IBM direct 
access devices. 

Note: Before using bytes 2 and 3, read the description of word 4. 

Byte 2 Block overhead, keyed block — the number of bytes required 

for gaps and check bits for each keyed block other than the 
last block on a track. 

Byte 3 Block overhead — the number of bytes required for gaps and 

check bits for a keyed block that is the last block on a track. 
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Bytes 2-3 Block overhead — ^the number of bytes required for gaps and 
check bits for any keyed block on a track including the last 
block. Use of this form is indicated by a 1 m bit 4, byte 1 of 
word 4. 

Basic overhead — ^the number of bytes required for the count 
field. Use of this form is indicated by a 1 in bit 3, byte 1 of 
word 4. 



Word 4 



Byte Block overhead, block without key — ^the number of bytes to 

be subtracted from word 3, bytes 2 or 3 or bytes 2 and 3, if a 
block is not keyed. 



Byte 1 



If bit 3, byte 1 of word 4 is 1, this byte contains the modulo 
factor for a modulo device. 



Bit If on, the number of cylinders, as indicated in 

word 2, bytes and 1 are invalid. 

Bit 1 Reserved. 

Bits 2-3 If on, indicates a 3380 is attached to a 3880 

Model 13 or 23. 

Bit 3 If on, indicates a modulo device (3375, 3380). 

For information on how to calculate the 
number of data bytes required for a data 
block for a modulo device, see the device data 
in Data Administration Guide. 

Bit 4 If on, bytes 2 and 3 of word 3 contain a 

halfword giving the block overhead for any 
block on a track, including the last block. 

Bits 5-6 Reserved. 

Bit 7 If on, a tolerance factor must be applied to all 

blocks except the last block on the track. 

Bytes 2-3 Tolerance factor — this factor is used to calculate the effective 
length of a block. The calculation should be performed as 
follows: 

Step 1 add the block's key length to the block's data 

length. 

Step 2 test bit 7 of byte 1 of word 4. If bit 7 is 0, 

perform step 3. If bit 7 is 1, multiply the sum 
computed in step 1 by the tolerance factor. 
Shift the result of the multiplication 9 bits to 
the right. 
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Step 3 add the appropriate block overhead to the 

value obtained above. 

If bit 3, byte 1 of word 4 is 1, bytes 2 and 3 contain the 
overhead for the data or key field. 

If your program specifies DEVTAB and RPS, or specifies UCBLIST, the 
next fuUword contains the following information: 

Words 

Bytes 0-1 RO overhead for sector calculations 

Byte 2 Number of sectors for the device 

Byte 3 Number of data sectors for the device 

Figure 29 on page 134 shows the output for each device type that results from 
issuing the DEVTYPE macro. 

Note: If your program specifies UCBLIST, the output consists of one 6-word 
entry for every UCB address contained in the UCB list. 



Return Codes from the DEVTYPE Macro 



Control is returned to your program at the next executable instruction following the 
DEVTYPE macro instruction. Register 15 contains a return code from the 
DEVTYPE macro. The return codes and their meanings are as follows: 



Code Meaning 

00(X'00' ) Indicates that the information concerning the ddname you specified 
has been successfully moved to your work area. 

04(X'04') Indicates that the ddname you specified was not found. 
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IBM 
Device^ 2 


Maximum 
Record Size 
(Word 1, in 
Decimal) 


DEVTAB (Words 2, 3, and 
4, in Hexadecimal) 


RPS (Word 5, 
in Hexadecimal) 


2540 Reader 


80 


Not Applicable 


Not Applicable 


2540 Reader w/CI 


80 


Not Applicable 


Not Applicable 


2540 Punch 


80 


Not Applicable 


Not Applicable 


2540 Punch w/CI 


80 


Not Applicable 


Not Applicable 


2501 Reader 


80 


Not Applicable 


Not Applicable 


2501 Reader w/CI 


80 


Not Applicable 


Not Applicable 


3890 Document 
Processor 


80 


Not Applicable 


Not Applicable 


3505 Reader 


80 


Not Applicable 


Not Applicable 


3505 Reader w/CI 


80 


Not Applicable 


Not Applicable 


3525 Punch 


80 


Not Applicable 


Not Applicable 


3525 Punch w/CI 


80 


Not Applicable 


Not Applicable 


1403 Printer 


1202 


Not Applicable 


Not Applicable 


1403 w/UCS 


1202 


Not Applicable 


Not Applicable 


3203 Model 5 Printer 


132 


Not Applicable 


Not Applicable 


3211 Printer 


1322 


Not Applicable 


Not Applicable 


3262 Model 5 Printer 


132 


Not Applicable 


Not Applicable 


4245 Printer 


132 


Not Applicable 


Not Applicable 


4248 Printer 


1324 


Not Applicable 


Not Applicable 


3800 Printing Subsystem 


1363 


Not Applicable 


Not Applicable 


3400 (9-track, p.e.) 


32760 


Not Applicable 


Not Applicable 


3400 (9-track, d.d.) 


32760 


Not Applicable 


Not Applicable 


3400 (7-track) 


32760 


Not Applicable 


Not Applicable 


3480(18-track) 


32760 


Not Applicable 


Not Applicable 


2305 Model 2 
Fixed-Head Storage 


14660 


006000083 AOAO 1 2 1 5B080200 


0140B4B1 


3330/3333 Disk Storage 


13030 


019B0013336DBFBF38000200 


OOED807C 


3330V MSS Virtual 
Volume 


13030 


019B0013336DBFBF38000200 


OOED807C 



Figure 29 (Part 1 of 2). Output from DEVTYPE Macro 
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IBM 
Device^ 2 


Maximum 
Record Size 
(Word 1, in 
Decimal) 


DEVTAB (Words 2, 3, and 
4, in Hexadecimal) 


RPS (Word 5, 
in Hexadecimal) 


3330 Model 11 (or 3333 
Model 11) Disk Storage 


13030 


032F0013336DBFBF38000200 


00ED807C 


3340 Disk Storage (35 
megabytes) 


8368 


015D000C2157F2F24B000200 


0125403D 


3340/3344 Disk Storage 
(70 megabytes) 


8368 


0230001E4B36010B52080200 


0125403D 


3350 Disk Storage 


19069 


0230001E4B36010B52080200 


0185807B 


3375 Disk Storage 


32760 


03BFOOOC8CAOOOE0201000Br 


0340C4BB 


3380 Models A04, AA4, 
and B04 Disk Storage 


32760 


0376000FBB6001002010010B 


04E0DED6 


3380 Models A04, AA4, 
and B04 Disk Storage 
(attached to a 3880 
Model 13 or 23) 


32760 


0376000FBB6001002030010B 


04E0DED6 


3380 Models AD4 and 
BD4 Disk Storage 


32760 


0376000FBB6001002010010B 


04E0DED6 


3380 Models AE4 and 
BE4 Disk Storage 


32760 


06EB000FBB6001002010010B 


04E0DED6 


2250 Model 3 Display 
Unit 




Not Applicable 


Not Applicable 


1030,1050,8363, 
TWX,2250,S360 


Not Applicable 


Not Applicable 


Not Applicable 


115A,1130 


Not Applicable 


Not Applicable 


Not Applicable 


2780 


Not Applicable 


Not Applicable 


Not Applicable 


2740 


Not Applicable 


Not Applicable 


Not Applicable 



Figure 29 (Part 2 of 2). Output from DEVTYPE Macro 

Notes to Figure 29: 

1 



CI — card image feature; d.c. — data conversion; d.d. — dual density; 
p.e. — ^phase encoding; UCS — ^universal character set; w/ — with. 

Although certain models can have a larger Une size, the minimum line size is 
assumed. 

The IBM 3800 Printing Subsystem can print 136 characters per line at 
10-pitch, 163 characters per line at 12-pitch, and 204 characters per line at 
15-pitch. The machine default is 136 characters per line at 10-pitch. 

The IBM 4248 Printer returns 132 characters even if the 168 Print Position 
Feature is installed on the device. 
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DEVTYPE — List Form 



The list form of the DEVTYPE macro is only valid with the UCBLIST function. It 
is used to construct an empty parameter List. By specifying MF=L you construct a 
parameter list, and you can subsequently supply the values by specifying the 
execute form of the macro. 



name! 


DEVTYPE 


, (area-addrx,area-size) 

,UCBLIST=YES 

,MF=L 



namel 



label of the parameter list to be constructed. It must also be specified in the 
corresponding MF=E form. 



DEVTYPE — ^Execute Form 



The execute form of the DEVTYPE macro is only valid with the UCBLIST 
function. It can be used to modify a parameter list and call the DEVTYPE 
function. 



[namel] 


DEVTYPE 


,(area-addrx,area-size) 
,UCBLIST= (ucbl-addrx, ucbl-num) 
,MF=(E,/iamei) 



namel 



label of the parameter list constructed by the corresponding MF=L form. 



Reading and Modifying a Job FUe Control Block 



To accomplish the functions that are performed as a result of an OPEN macro 
instruction, the open routine requires access to information that you have supplied 
in a data definition (DD) statement. This information is stored by the system in a 
job file control block (JFCB). 

In certain applications, you may find it necessary to modify the contents of a JFCB 
before issuing an OPEN macro instruction. For example, suppose you are adding 
records to the end of a sequential data set. You might want to add a secondary 
allocation quantity to allow the existing data set to be extended when the space 
currently allocated is exhausted. To assist you, the system provides the RDJFCB 
macro instruction. This macro instruction causes a specified JFCB to be moved 
from the scheduler work area (SWA), where it is stored, to an area specified in an 
exit list. The use of the RDJFCB macro instruction with an exit list is shown under 
"Example" on page 138. When you subsequently issue the OPEN macro 
instruction, you must indicate, by specifying the TYPE=J operand, that you want 
to open the data set using the JFCB in the area you specified. 

The RDJFCB macro also allows you to retrieve allocation information (all JFCBs 
and all volume serial numbers) for the data sets in a concatenation. You may either 
select data sets or, by default, retrieve the information for all data sets in the 
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concatenation. Figure 33 on page 146 illustrates how you can use RDJFCB to 
retrieve this information. 

Caution: If you set the bit JFCNWRTT in the field JFCBTSDM to 1 before you 
issue the OPEN macro instruction, the JFCB is not written back to the SWA at the 
conclusion of open processing. OPEN TYPE=J normally moves your program's 
modified copy of the JFCB to the scheduler work area (SWA), replacing the 
system copy. To ensure that this move is done, your program must set bit zero (0) 
of the JFCBMASK+4 field to 1. The JFCBMASK format is shown in the Internal 
Data Areas section of Open/ Close /EOV Logic. If the user JFCB, which the system 
used to open the data set, is not written back to SWA (JFCNWRTT set on), then 
errors may occur during EOV or close processing. 

Some of the modifications that are commonly made to the JFCB include: 

• Moving the creation and expiration date fields of the DSCB into the JFCB (see 
"Using RDJFCB for MSS Virtual Volumes" on page 140). 

• Moving the secondary allocation quantity from the DSCB into the JFCB (see 
"Using RDJFCB for MSS Virtual Volumes" on page 140). 

• Moving the DCB fields from the DSCB into the JFCB. 

• Adding volume serial numbers to the JFCB (see "Using RDJFCB for MSS 
Virtual Volumes" on page 140 and "RDJFCB Security" on page 140). 

Volume serial numbers in excess of five are written to the JFCBX (extension) 
located in the SWA. The JFCBX cannot be modified by user programs. 

• Modifying the data set sequence number field in the JFCB. 

• Modifying the number-of -volumes field in the JFCB (see "Using RDJFCB for 
MSS Virtual Volumes" on page 140). 

• Setting bit JFCDQDSP in field JFCBFLG3 to invoke the tape volume DEQ at 
demount facility (see "DEQ at Demount Facility for Tape Volumes" on 
page 147). 

• Modifying the JFCRBIDO field in the JFCB to cause high-speed positioning to 
a specific data block on a 3480 tape volume. 



RDJFCB — ^Read a Job File Control Block 



The RDJFCB macro instruction causes a job file control block (JFCB) to be 
moved from the SWA (scheduler work area) into an area of your choice as 
identified via the EXLST parameter of the DCB macro for each data control block 
specified. 



[symbol] 


RDJFCB 


{dcb-address 
\{options)\^..,) 
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dcb-address,[ioptions)\ 

(same as the dcb-address, option 1, and option2 operands of the OPEN 
macro instruction, as shown in Data Administration: Macro Instruction 
Reference), except for the MODE operand, which is not valid with the 
RDJFCB macro. 

The option operands do not affect RDJFCB processing. You can, however, 
specify them in the list form of the RDJFCB macro instruction and refer to 
the generated parameter list with the execute form of the macro. 

Example: In Figure 30, the macro instruction at EXl creates a parameter Ust for 
two data control blocks: INVEN and MASTER. In creating the list, both data 
control blocks are assumed to be opened for input; option2 for both blocks is 
assumed to be DISP. The macro instruction at EX2 moves the system-created 
JFCBs for INVEN and MASTER from the SWA into the area you specified, thus 
making the JFCBs available to your problem program for modification. The macro 
instruction at EX3 modifies the parameter list entry for the data control block 
named INVEN and indicates, through the TYPE=J operand, that the problem 
program is supplying the JFCBs for system use. 



EXl 



EX2 



EX3 



INVEN 

MASTER 

LSTA 



RDJFCB ( INVEN , , MASTER ) , MF=L 



RDJFCB MF=(E,EX1) 



OPEN ( , ( RDBACK , LEAVE ) ) , TYPE= J , MF= ( E , EX 1 ) 



DCB 

DCB 

DS 

DC 

DC 



JFCBAREA DS 



LSTB 



DS 



EXLST=LSTA, . . 

EXLST=LSTB, . . 

OF 

X'07' 

AL3 (JFCBAREA) 



0F,176C 



OF 



Figure 30. Sample Code Using RDJFCB Macro 



Multiple data control block addresses and associated options may be specified in 
the RDJFCB macro instruction. This facility makes it possible to read several job 
file control blocks in parallel. 
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An exit list address must be provided in each DCB specified by an RDJFCB macro 
instruction. Each exit list must contain an active entry that specifies the virtual 
storage address of the area into which a JFCB is to be placed. 

Two kinds of JFCB entries may appear in the exit list. Each is briefly explained in 
the following text. A full discussion of the exit list and its use is contained in Data 
Facility Product: Customization. 



Type 07 JFCB Exit List Entry 



The type 07 JFCB exit list entry allows a variety of functions to the user, as 
described in the following text. 

The format of the Type-07 JFCB exit list entry is as follows: 



Types of 
Exit List 
Entry 


Hexadecimal 
Code (High- 
Order Byte) 


Contents of Exit List Entry 
(Low-Order Bytes) 


Job fUe 
control 
block 


07 


Address of a 176-byte area to be provided 
if the RDJFCB or OPEN (TYPE=J) 
macro instruction is used. This area must 
begin on a fullword boundary and must be 
located within the user's region. Also, 
users running in 31 -bit addressing mode 
must ensure that this area is located below 
16 megabytes virtual. 



The virtual storage area into which the JFCB is read must be at least 176 bytes 
long. Each exit list entry must be 4 bytes long. The system recognizes only the first 
occurrence of an exit list entry code. Indicate the end of the exit list by setting the 
high order bit in the entry code to 1. 

The DCB may be either open or closed when this macro instruction is executed. 

If the JFCB is read successfully for all DCBs in the parameter list, return code is 
placed in register 15. If the JFCB is not read for any of the DCBs because the 
DDNAME is blank, or a DD statement is not provided, return code 4 is placed in 
register 15. 

Warning: The following errors cause the results indicated: 



Error 


Result 


A DD statement has not been 
provided. 


Return code 4 is placed in register 15. 


DDNAME field in DCB is blank. 


A write-to-programmer is issued, the 
request for this DCB is ignored, and 
return code 4 is placed in register 15. 



Chapter 6. System Macro Instructions 139 



Error 


Result 


A virtual storage address has not 
been provided. 


Abnormal termination of task. 



If you want to open a VTOC data set to change its contents (that is, open it for 
OUTPUT, OUTIN, INOUT, UPDAT, OUTINX, or EXTEND), your program 
must be authorized under the Authorized Program Facility (APF). APF provides 
security and integrity for your data sets and programs. Details on how you 
authorize your program are provided in System Programming Library: Supervisor 
Services and Macro Instructions. 

If the RDJFCB routine fails while processing a DCB associated with your RDJFCB 
request, your task is abnormally terminated. None of the options available through 
the DCB ABEND exit, as described in Data Facility Product: Customization, are 
available when a RDJFCB macro instruction is issued. 

When using concatenated data sets, the RDJFCB routine modifies only the first 
JFCB. 

Using RDJFCB for MSS Virtual Volumes: Care must be taken in usmg RDJFCB if 
the data set resides on MSS virtual volumes such that: 

• The expiration date added does not conflict with other volumes within the 
specified MSVGP. 

• The secondary allocation quantity should be in cylinder increments and be a 
multiple or submultiple of the primary allocation quantity to avoid 
fragmentation. 

• The number of volumes must not exceed the number available in the specified 
MSVGP. 

• Any volume serial numbers added to the JFCB should exist in the MSVGP. 

RDJFCB Security: The volume serial numbers specified in the user-supplied JFCB 
will be compared with the volume serial numbers in the system JFCB located in the 
SWA. Each different volume serial number will be enqueued exclusively. The 
volumes will stay enqueued until the job step terminates, because the close routines 
will not dequeue the volumes. If the job step already has the volume open, OPEN 
TYPE=J will continue. If the volume is enqueued by another job step, a 413 
abend will occur with a return code of 04. 

Some JFCB modifications can compromise the security of existing 
password-protected data sets. The following modifications are specifically not 
allowed, unless the program making the modifications is authorized or can supply 
the password: 

• Changing the disposition of a password-protected data set from OLD or MOD 

to NEW. 

• Changing the data set name of one or more of the volume serial numbers when 
the disposition is NEW. 
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• Changing the label processing specifications to bypass label processing. 

Note: An authorized program is one that is either in supervisor state, executing in 
one of the system protection keys (keys through 7), or authorized under the 
Authorized Program Facility. 

RDJFCB Use by Authorized Programs: If you change the data set name in the 
JFCB, you should do a system enqueue on the major name of "SYSDSN" for the 
substituted data set name. To use the correct interface with other system functions 
(for example, partial release), the ENQUEUE macro should include the TCB of 
the initiator and the length of the data set name (with no trailing blanks). When 
you complete processing of the data set, you should use the DEQ macro to release 
the resources. If the substituted data set name is enqueued by another job step, a 
913 abend occurs with a return code of X' IC 

Usii^ RDJFCB to Process a Multivolume Dinct Data Set: This use of RDJFCB and 
OPEN TYPE=J permits your program to process a multivolume data set. To do so, 
your program must cause the open routines to build a data extent block for each 
volume and issue mount messages for them. Your program must use the RDJFCB 
macro to read in the JFCB, and open each volume of the data set. The following 
code illustrates the procedure: 
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RDJFCB 


DCB1 


READS IN THE JFCB 




SR 


R3,R3 


CLEARS REG 3; IT WILL 


* 






HOLD COUNT OF VOLS TO 


* 






BE OPENED 




IC 


R3,JFCBNV0L 


PUTS # OF VOLS 


« 






IN REG 3 




LA 


R4,DCB1 


R4 POINTS TO DCB FOR 


* 






VOL TO BE OPENED 




LA 


R5,l 


PUTS SEQUENCE # OF 


* 






FIRST VOL TO BE 


* 






OPENED IN REG 5 


LOOP 


EQU 


* 






STH 


R5,JFCBVLSQ 


PUTS SEQ # OF VOL 


* 
* 






TO BE OPENED WHERE 
OPEN RTNS t.OOK 



OPEN ({R4) , OUTPUT ) ,TYPE= J OPENS ONE VOL 

* NOTE THAT THE TYPE=J OPTION OF THE MACRO MUST BE USED 

LA R4,DCB2-DCB1 (R4) INCREMENT REG 4 TO 

* POINT TO THE DCB FOR 

* THE NEXT VOL TO BE 

* OPENED 

LA R5,1(R5) INCREMENT TO SEQ # OF 

* NEXT VOL TO BE OPENED 
BCT R3,L00P LOOP UNTIL ALL VOLS 

* OPEN 



JFCB 


DS 


CL176 




ORG 


JFCB+70 


JFCBVLSQ 

* 


DS 


H 




ORG 


JFCB+117 


JFCBNVOL 


DS 


FL1 



# OF VOLS IN DATA SET 



JFCB READ IN HERE 

SEQ # OF VOL TO BE 

OPENED 
JFCB+117 
FL1 
ORG 

* MAPPING MACRO lEFJFCBN MAY ALSO BE USED 

DCB 1 DCB DDNAME=S YSUT 1 , MACRF= ( E ) , EXLST=EXITS , DSORG=PS 
DCB2 DCB DDNAME=SYSUT1 ,MACRF=(E) ,EXLST=EXITS,DSORG=PS 
DCB3 DCB DDNAME=SYSUT1,MACRF=(E) ,EXLST=EXITS,DSORG=PS 
DCB4 DCB DDNAME=S YSUT 1 , MACRF= ( E ) , EXLST=EXITS , DSORG=PS 
DCB5 DCB DDNAME=SYSUT1,MACRF=(E) ,EXLST=EXITS,DSORG=PS 

* THIS PROCEDURE WORKS FOR 5 VOLS OR LESS; THE JFCB 

* EXTENSION, WHICH IDENTIFIES ADDITIONAL VOLS, CAN'T 

* BE READ IN 

EXITS DS OF 

DC X'87',AL3(JFCB) 87 IDENTIFIES THIS AS 

* THE EXIT LIST ENTRY 

* THAT SHOWS WHERE JFCB 

* WILL BE READ IN 



Type 13 JFCB Exit List Entry 



The type 13 JFCB exit list entry allows you to retrieve selected allocation 
information, as described in the following text. 

The format of the type 13 JFCB exit list entry is as follows: 
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Types of 
Exit List 
Entry 


Hexadecimal 
Code (High- 
Order Byte) 


Contents of Exit List Entry 
(Low-Order Bytes) 


Job file 
control 
block 


13 


Address of an allocation retrieval list. 
OPEN TYPE=J does not recognize this 
exit list entry. This entry allows you to use 
RDJFCB to obtain copies of the JFCBs 
for data sets in a concatenation, and lists 
of all the volume serial numbers for those 
data sets. You may select JFCBs in the 
concatenation or by defauh, retrieve all of 
them. See Figure 31 on page 144 for the 
allocation retrieval list format, and 
Figure 33 on page 146 for an example of 
usage. 



Using RDJFCB to Retrieve Allocation Information: RDJFCB uses DCB exit Ust 
entry type 13 to retrieve allocation information (JFCBs and volume serial 
numbers) for concatenated data sets. The exit list entry code is X' 13', and is 
defined as "retrieve allocation information." The second through fourth bytes of 
this entry must point to an "Allocation Retrieval List," as described in Figure 31 
on page 144. When you issue RDJFCB, this DCB exit list entry causes retrieval of 
JFCBs for the specified concatenated data sets, and lists of all volimie serial 
numbers for these data sets. You may either select JFCBs in the concatenation or 
by default, retrieve all of them. OPEN TYPE = J does not recognize this exit list 
entry. RDJFCB uses the parameter list to receive and return information about the 
request. You may use the IHAARL macro (shown below) to generate and map the 
allocation retrieval list. 



[symbol] 


IHAARL 


fDSECT={YESlNOn 

(,PREFIX=prefixJ 

I,DESCR=|YES|NO}l 



DSECT={YES|NO| 

specifies whether the symbol at the beginning of the generated area appears 
on a DSECT instruction or a DC instruction. For DSECT=NO, the symbol 
appears on a DC instruction. The default is DSECT=YES. 

PREFIX=prefix 

allows you to invoke the macro more than once per assembly. Specifies a 
character string with which all generated symbols are to be prefixed. Do not 
specify delimiters, such as quotation marks. If you omit this operand or 
specify a null value, the prefix defaults to the characters ARL. 

DESCR={YES I NO} 

specifies whether the macro expansion includes the macro description 
(prolog). The default is DESCR=NO. 
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Figure 31 and Figure 32 describe the fonnats of the allocation retrieval list and 
allocation retrieval area, respectively. 



Name 



Offset 



Bytes 



Description 



The Following Fields Are Set by the Caller of RDJFCB: 



ARLLEN 
ARLIDENT 
ARLOPTl 
ARLLANY 



ARLRSVDl 
ARLRETRV 

ARLFIRST 



OO(X'OO') 
02(X'02') 
04(X'04') 



05(X'05') 
12(X'0C') 

14(X'0E') 



2 
2 
1 



1 

.xxxxxxx 

7 

2 



The Following Fields Are Set by RDJFCB: 



ARLAREA 
ARLPOOL 
ARLRLEN 
ARLRTRVD 

ARLCONC 

ARLRCODE 



16(X'10') 
20(Xn4') 
21(X'15') 
24(X»18') 

26(X'1A') 

28(X'1C') 



ARLRSVD2 



29(X'1D') 



Length of this area. Value must be 36 or more. 

EBCDIC 'AR' 

Option byte. 

Allocation retrieval area must be below 16Mb line. 

Allocation retrieval area may be above 16\fb line. 

Reserved. Must be zero. 

Reserved. Must be zero. 

Number of data sets for which to retrieve information. If 

0, retrieve all in the concatenation. 

Number of first data set in concatenation for which to 

retrieve information. or 1 specifies retrieval of 

information beginning with first data set in the 

concatenation. 



Address of allocation retrieval area. See Figure 32. 

Storage subpool containing allocation retrieval area. 

Length of allocation retrieval area. 

Number of concatenated data sets for which JFCBs were 

retrieved. 

Number of concatenated data sets. If no concatenation, 

this value is 1. 

Reason Code: 

s Requested information was read. 

The following reason codes are related to return code 8: 

4 = ARLFIRST is greater than ARLCONC. 

8 = Insufficient storage to read information. 
ARLPOOL and ARLRLEN describe what could not 
be obtained. 
Reserved. Used by RDJFCB. 



Figure 31. Format of the Allocation Retrieval List 
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)ffset Bytes Description 

)0(X'00') 2 Length of the information for this data set (including this field). The 

length is rounded up to a multiple of four so the starting address of the 
allocation retrieval area plus the value in the length field designates the 
address of the retrieval area for the next data set in the concatenation, if 
requested. 

32(X'02') 2 Reserved. Set to zero. 

04(X'O4') 176(dec) JFCB 

180(X'B4') variable Sixth and subsequent volume serial numbers. Determined by the value in 

JFCBNVOL. If the number of volume serial numbers is fewer than the 
specified volume count, entries at the end of the list may contain all 
blanks. If the first byte of an entry is X'FF', the JCL specified 
VOL=REF and the volume could not be determined. 

Figure 32. Format of the Allocation Retrieval Area 

Return code indicates that RDJFCB has filled in the allocation retrieval list fields. 
When you have finished using information from the retrieval areas, you should 
issue FREEMAIN to free the areas. To determine whether the release of the Data 
Facility Product on your system is capable of using exit list entry type X' 13 ' to 
retrieve allocation information, set the ARLAREA field in the allocation retrieval 
list to zeros before issuing RDJFCB. If the ARLAREA is still zeros and the 
ARLRCODE field contains reason code 00 when RDJFCB returns control to your 
program, your release of DFP does not support this function. 

Ejutmpie: In Figure 33 on page 146, the macro instruction at ALLOCINF creates 
a parameter list for one DCB (INDCB), assumed to be open for input. The JFCBs 
and volume serial numbers are retrieved for all data sets allocated to DD name 
SYSLIB. 
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***JCL FOR FOLLOWING INVOCATION OF RDJFCB: 

//SYSLIB DD DISP=SHR,DSN=DEPT61 .ROUTINES 
// DD DISP=SHR,DSN=CORPORAT. ROUTINES 
// DD DISP=SHR,DSN=SYS1 .FORTLIB 



♦♦♦EXAMPLE CODE TO INVOKE RDJFCB ALLOCATION INFORMATION RETRIEVAL; 

♦ GET A COPY OF THE JFCB FOR THE FIRST OR ONLY DATA SET ALLOCATED 

♦ TO SYSLIB AND TRY TO READ THE JFCBS AND VOLUME SERIAL NUMBERS 

♦ FOR ALL DATA SETS ALLOCATED TO SYSLIB. 



ALLOCINF RDJFCB (INDCB) 

LTR R15,R15 

BNZ NOJFCB 

ICM R1 ,X'F' ,SLBAREA 

BZ OLDSYSTM 

USING SLBSTRT,R1 

CLI SLBRCODE,0 

BNE NOJFCB 
* 

♦ LOOP THROUGH THE JFCBS IN THE AREA TO WHICH SLBAREA POINTS. 

♦ CODE CAN BE INSERTED HERE TO PRINT THE DATA SET NAMES AND 

♦ VOLUME SERIAL NUMBERS . 



TEST RDJFCB RETURN CODE 

BRANCH IF INFORMATION NOT AVAILABLE 

GET AND TEST ADDRESS OF ARL 

GO IF SYSTEM DOES NOT SUPPORT ARL 

ESTABLISH ADDRESSABILITY TO AREA 

TEST RDJFCB REASON CODE 

BRANCH IF INFORMATION NOT AVAILABLE 



OLDSYSTM DS 



OH 



ROUTINE TO HANDLE JUST LIBJFCB 



NOJFCB 



DS 



OH 



ROUTINE TO HANDLE INABILITY TO GET THE 
JFCB. THE DATA SET MAY NOT BE ALLOCATED, 



SLBOPNX 



DS 



OH 



DCB OPEN EXIT ROUTINE FOR SYSLIB. 
HANDLES RECFM, LRECL, AND BLKSIZE. 



INDCB 



INEXLST 



* 
SLBSTRT 



DS 

DC 
DC 
DC 

DC 
DC 

DC 



DSORG=PO , DDNAME=SYSLIB , MACRF=R , SYNAD=INERROR , 

EXLST=INEXLST 

ENTRY CODE FOR OPEN EXIT ROUTINE 
ADDR OF DCB OPEN EXIT ROUTINE 
ENTRY CODE TO RETRIEVE ALLOCATION 

INFORMATION 
ADDR OF ALLOCATION RETRIEVAL LIST 
ENTRY CODE TO RETRIEVE FIRST JFCB AND 

INDICATE LAST ENTRY IN LIST 
ADDR OF JFCB FOR FIRST DATA SET 



OF'O' ,X'05' 
AL3 (SLBOPNX) 
X'13' 

AL3(SLB) 
X'87' 



AL3 (LIBJFCB) 
AN ALLOCATION RETRIEVAL LIST FOLLOWS, POINTED TO BY DCB EXIT LIST. 



LIBJFCB 



IHAARL DSECT=NO,PREFIX=SLB 

DC OF ' ' 

DC CLI 76' • FIRST JFCB 



Figure 33. Sample Code Retrieving Allocation Information. IHAARL PREFIX^SLB requires Assembler H. 
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DEQ at Demount Facility for Tape Volumes 



This facility is intended to be used by long-ranning programs that create an 
indefinitely long tape data set (such as a log tape). Use of this facility by such a 
program permits the processed volumes to be allocated to another job for 
processing (such as data reduction). This processing is otherwise prohibited unless 
the indefinitely long data set is closed and dynamically unallocated. 

You may invoke this facility only through the RDJFCB/OPEN TYPE= J interface 
by setting bit JFCDQDSP (bit 0) in field JFCBFLG3 (offset 163 or X'A3') to 1. 
The volume serial of the tape is dequeued when the volume is demounted by OPEN 
or EOV with message IEC502E when all the following conditions are present: 

• The tape volume is verified for use by OPEN or EOV. 

• JFCDQDSP is set to 1. 

• The program is APF authorized (protect key and supervisor/problem state are 
not relevant). 

• The tape volume is to be immediately processed for output. That is, either 
OPEN verifies the volume and the OPEN option is OUTPUT, OUTIN, or 
OUTINX; or EOV verifies the volume and the DCB is opened for OUTPUT, 
OUTIN, INOUT, or EXTEND, and the last operation against the data set was 
an output operation (DCBOFLWR is set to 1). 

Note that, in order for EOV to find JFCDQDSP set to 1, the program must not 
inhibit the rewrite of the JFCB by setting bit 4 of JFCBTSDM to 1. 

The tape volume is considered verified after file protect, label tjrpe, and density 
conflicts have been resolved. The volume is dequeued when demounted after this 
verification, even if further into OPEN or EOV processing the volume is rejected 
because of expiration date, security protection, checkpoint data set protection, or 
an I/O error. 

When the volume serial is dequeued, the volume becomes available for allocation to 
another job. However, because the volume DEQ is performed without unallocating 
the volume, care must be exercised both by the authorized program and the 
installation to prevent misuse of the DEQ at demount facility. A discussion of such 
misuse follows. 

1. The authorized program must not close and reopen the data set using the tape 
volume DEQ at demount facility. If it does, one of the following can occur: 

a. The dequeued volume may be mounted and in use by another job. When 
the volume is requested for mounting, for the authorized program, the 
operator is unable to satisfy the mount. Therefore, the operator must 
either cancel the requesting job, cancel the job using the volume, wait for 
the requesting job to time out, or wait for the job using the volume to 
terminate. 

b. The dequeued volume may be allocated to another job but not yet in use. 
The operator mounts the volume to satisfy the mount request of the 
authorized job. When the volume is requested for mounting by the other 
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job, the operator is unable to satisfy the mount request, and is faced with 
the same choices as in a, above. 

c. The dequeued volume may not yet be allocated to another job and the 
volume is mounted to satisfy the mount request of the authorized job. 
Another job may allocate the volume and, when the volume is requested 
for mounting, the situation is the same as in b, above. 

It is the responsibility of the installation that permits a program to run with 
APF authorization to ensure that it does not close and reopen a data set using 
the DEQ at demount facility. 

2. Care should be exercised when an authorized program uses the DEQ at 
demount facility (data set 1) but processes another tape data set (data set 2). 
Assume the same volume serial numbers have been coded in the DD 
statements for data set 1 and data set 2. As the volumes of data set 1 are 
demounted, they are dequeued even though those volumes may yet be 
requested for data set 2. All the problems explained in a, b, and c in 1, above, 
may occur as data set 2 and another job contend for a dequeued volume. 

This problem should not occur, given the intended use of the DEQ at demount 
facility; that is, a long-running application creating an indefinitely long tape 
data set. This type of application is not normally invoked through batch 
execution with user-written DD statements. 

3. After a volume has been demounted and dequeued because of the DEQ at 
demount facility, the volume is not automatically rejected by the control 
program when mounted in response to a specific or nonspecific mount request. 
Without the use of the facility, the control program can recognize (by the 
ENQ) that the volume is in use, and reject the volume. Therefore, operations 
procedures, in effect to prevent incorrect volumes from being mounted, should 
be reviewed in the light of reduced control program protection from such errors 
when the DEQ at demount facility is used. Specifically, if a volume is 
remounted for an authorized program and the volume had been used previously 
by that authorized program, duplicate volume serial numbers will exist in the 
JFCB, and the control program will be unable to release the volume during 
EOV processing. 

4. Checkpoint/restart considerations are discussed in Checkpoint/ Restart User's 
Guide. 



OPEN— Initialize Data Control Block for Processing the JFCB 



The OPEN macro instruction initializes one or more data control blocks so that 
their associated data sets can be processed. 

A full explanation of the operands of the OPEN macro instruction is contained in 
Data Administration: Macro Instruction Reference. The TYPEa= J option, because it 
is used in conjunction with modifying a JFCB, should be used only by the system 
programmer or under the system programmer's supervision. 

The parameters of the OPEN TYPE= J macro instruction are: 
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[symbol] 


OPEN 


(dcb-addr 

.[(options)],...) 

l,TYPE=Jl 



TYPE=J 

specifies that, for each data control block referred to, you have supplied a 
job file control block (JFCB) to be used during initialization. A JFCB is an 
internal representation of information in a DD statement. 

During initialization of a data control block, its associated JFCB may be 
modified with information from the data control block or an existing data set 
label or with system control information. 

The system always creates a job file control block for each DD control 
statement. The job file control block is placed in the SWA (scheduler work 
area). Its position, in relation to other JFCBs created for the same job step, 
is noted in a table in virtual storage. 

When the TYPE=J operand is specified, you must also supply a DD 
statement. However, the amount of information given in the DD statement is 
at your discretion, because you can modify many fields of the system-created 
job file control block. If you specify DUMMY on your DD statement, the 
open routine will ignore the JFCB DSNAME and open the data set as 
dummy. (See Figure 30 on page 138 for an example of coding that 
modifies a system-created JFCB.) 

Notes: 

1. The DD statement must specify at least: 

• Device allocation (refer to JCL User's Guide for methods of preventing share 
status) 

• A ddname corresponding to the associated data control block DCBDDNAM 
field 

2. The MODE operand is not shown here because it is not allowed with the TYPE=J 
operand of the OPEN macro instruction. 



High>Speed IBM 3480 Positioning 



High-speed positioning for 3480 tape drives is available when opening a tape data 
set on an IBM standard-labeled tape for either EXTEND (OUTINX, EXTEND, or 
DISP=MOD), or when opening to the beginning of such a data set. To invoke 
high-speed positioning, your program must modify certain fields in the JFCB and 
use OPEN TYPE^J to open the data set. 

You should use the following procedure to modify the JFCB: 

1 . Issue the RDJFCB macro to have the system move the JFCB into your work 
area. 
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2. Set the JFCPOSID flag in the JFCBFLG3 flag byte to indicate that you are 
providing a block ID for a high speed search. 

3. Move the block ID into the JFCRBIDO field of the JFCB. If you are opening 
to the beginning of a data set, use the block ID of the first header label record 
of that data set. If you are opening to the end of a data set (for example, to 
extend it), use the block ID of the tape mark immediately following the last 
block of user data in that data set. 

4. Issue the OPEN TYPE=J macro to have the system use your modified JFCB. 

After the tape is positioned, OPEN processes the trailer labels for the data set 
being extended. 

If you set the JFGPOSID flag off, OPEN positions the volume normally, as though 
the high-speed positioning feature were not active. 

If you set the JFCPOSID flag on, but do not provide a block ID in the JFCRBIDO 
field, OPEN positions the volume normally and does one of the following: 

• If you are opening to the beginning of a data set, OPEN inserts the block ID of 
the first header label record of that data set into the JFCRBIDO field. 

• If you are opening to the end of the data set, OPEN inserts the the block ID of 
the tape mark immediately following the last block of user data for that data 
set into the JFCRBIDO field. 

If the JFCPOSID flag is on during CLOSE processing, CLOSE inserts the block ID 
for the first header label record of the next data set (which may not exist) into the 
JFCRBIDC field. Therefore, if you deallocate the 3480 device and want to use the 
current block ID for subsequent processing, you must save the block ID before you 
CLOSE the data set. 

OPEN resets the JFCPOSID flag if either of the following conditions exists: 

• Your program issues an OPEN which is not TYPE= J. 

• The requested tape volume is not an IBM standard-labeled volume. 

• The requested unit is not a buffered tape device 
Notes: 

1. If you specify dynamic unallocation (with SVC 99, FREE^CLOSE on the DD 
statement, or the FREE option on the CLOSE macro), then the block ID for the 
next data set will not be available to your program. This is because dynamic 
unallocation frees the JFCB. 

2. When using high-speed positioning, specify the data set sequence number 
normally, either explicitly by LABEL=(seqno,SL) on the DD statement, or by 
default. 

After the system routines have used the JFCRBIDO field for high-speed 
positioning, they clear JFCRBIDO In the system's copy of the JFCB to prevent 
misinterpretation during a subsequent OPEN. 
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Ensuring Data Security by Validating the Data Extent Block 



Protecting one user's diata from inadvertent or malicious access by an unauthorized 
user depends on protection of the data extent block (DEB). The DEB is a critical 
control block because it contains information about the device a data set is 
mounted on, and describes the location of data sets on direct access device storage 
volumes. The DEB also contains the address of the appendage vector table 
(AVT). Using the AVT, an unauthorized user can modify the AVT to give control 
to a routine in supervisor state to read from and write to data sets to which access 
would otherwise be denied. 

To guarantee protection of the DEB, the DEBCHK macro instruction is provided. 
The DEBCHK macro instruction can be found in SYSl.MACLIB. The DEBCHK 
macro is issued by several components of the system control program. For 
example: 

• The open access method executors issue the macro to add the address of a 
DEB they have built to a list of valid addresses called the DEB table. The 
DEB validity-checking routine builds and maintains a DEB table for each job 
step. 

• The EXCP processor uses the macro to verify that the DEB passed with each 
EXCP request is in the DEB table. 

• The close component issues the macro to remove a DEB from the DEB table. 

If you code a routine that builds a DEB, you must add the address of the DEB you 
built to the DEB table. If you code a routine that depends on the validity of a DEB 
that is passed to your routine, you should verify that the DEB passed to your 
routine has a valid entry in the DEB table and points to your DCB or access 
method control block (ACB). Use the TYPE=ADD and the TYPE= VERIFY 
operands of the macro, respectively. 

To prevent an asynchronous routine from changing or deleting, or assigning a new 
DEB to a DCB, you must hold the local lock. In this case, you must use the branch 
entry to the DEBCHK verify routine. 

Additional detaUs about the functions provided by the DEB validity-checking 
routine and about the contents of the DEB table are available in Open/ Close/ EOV 
Logic. 

The DEBCHK macro instruction provides four functions: 

• Adds the address of a DEB to the DEB table, which is located in protected 
storage. The DEB table contains the address of every user DEB associated 
with a given job step. Every system control program component that builds a 
user DEB must add the address of that DEB to a DEB table. 

• Verifies that the DEB table associated with a given job step contains the 
address of a valid DEB and that the DEB points to the DCB (or ACB). Any 
system control program component or problem program can use this function 
to verify that a DEB is valid. 
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Deletes the address of a DEB from the DEB table. Any program that deletes a 
user DEB must, before it deletes the DEB, issue a DEBCHK macro with a 
TYPE=DELETE operand to delete the address of the DEB from the DEB 
table. If the DEB validity-checking routine encounters an error while deleting 
the address from the DEB table, the job step is abnormally terminated. 

Deletes the address of a DEB from the DEB table in the same way as the 
preceding function, except that, instead of terminating the job step, this 
function merely returns an error code in register 15. This function is provided 
to prevent reciuring abnormal termination. The format of the DEBCHK and a 
description of the operands follow: 



DEBCHK— Macro Specification 



[symbol\ 


DEBCHK 


cbaddr 

[,TYPE={VERffiY 1 ADD 1 DELETE | PURGE}] 

UAM={amtype | (amaddr) \ {(amreg))]] 

[,BRANCH={NO | YES}] 

l,TCBADDR=^t/rmI 

UKE\ADDR=address] 

ISAVREG^req] 

[,MF=LI 



cbaddr 

for BRANCH=NO 

RX-type address, (2-12), or (1) 

A control block address passed to the DEBCHK routine. This operand is 
ignored if MF=L is coded. For verify, add, and delete requests, cbaddr is 
the address of a DCB or ACB that points to the DEB whose address is either 
verified to be in the DEB table, added to the DEB table, or deleted from the 
DEB table. For the purge function, cbaddr is the address of the DEB whose 
pointer is to be purged from the table: No reference is made to the DCB or 
ACB. 

Note: A spooled DCB's DEB does not point back to the DCB, but to the 
spooled ACB; in this case, the DEBCHK should be issued against the ACB. 

for BRANCH=YES 

The A- type address of a 4-byte field, or a register (1) or (3-12), that 
points to the DCB or ACB containing the DEB to be verified. 

TYPE=|VERIFY | ADD | DELETE | PURGE} 

indicates the function to be performed. If MF=L is coded, TYPE is ignored. 
The functions are: 

VERIFY 

This function is assumed if the TYPE operand is not coded. The 
control program checks the DEB table to determine whether the DEB 
pointer is in the table at the location indicated by the DEBTBLOF 
field of the DEB. The DEB is also checked to verify that 
DEBDCBAD points to the DCB (or ACB) passed to DEBCHK. The 
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AM 



DEBAMTYP field in the DEB is compared to the AM operand value, 
if given. The two must be equal. TYPE= VERIFY may be issued in 
either supervisor or problem state. 

ADD 

The DEB and the DCB (or ACB) must point to each other before the 
DEB address can be added to the DEB table. Before the DEB pointer 
can be added to the table, the DEB itself must be queued on the 
current TCB DEB chain (the TCBDEB field contams the address of 
the first DEB in the chain). The DEB address is added to the DEB 
table at some offset into the table. That offset value is placed in the 
DEBTBLOF field of the DEB, and the access method type is inserted 
into the DEBAMTYP field of the DEB. A zero is placed in the 
DEBAMTYP field if the AM operand is not coded. TYPE=ADD can 
be issued only in supervisor state. 

DELETE 

The DEB and the DCB (or ACB) must point to each other before the 
DEB address can be deleted from the DEB table. TYPE=DELETE 
can be issued only in supervisor state. 

PURGE 

The DEB pointer is removed from the DEB table without checking the 
DCB (or ACB). TYPE=PURGE can be issued only in supervisor 
state. 



specifies an access method value. Each value corresponds to a particular 
access method type (note that BPAM and SAM have the same values): 

Type Value 



TCAMAP 


(X'84') 


SUBSYS 


(X'81') 


ISAM 


(X'80') 


BDAM 


(X»40') 


SAM 


(X'20') 


BPAM 


(X'20») 


TAM 


(X'lO') 


GAM 


(X'OS') 


TCAM 


(X'04') 


EXCP 


(X'02') 


VSAM 


(X'Ol') 


NONE 


(X'OO') 



The operand can be coded in one of the follov/ing three ways, only the first 
of which is valid for the list form (MF=L) of the instruction. 

amtype 

refers to the access method: ISAM, BDAM, SAM, BPAM, TAM 
(which refers to BTAM only), GAM, TCAM, EXCP, or VSAM. 
TCAMAP identifies a TCAM application-program DEB. SUBSYS 
identifies a subsystem of the operating system, such as a job entry 
subsystem. NONE indicates that no access method or subsystem is 
specified. 
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(amaddr) 

is the RS-type address of the access method value. This fonnat may 
not be coded when MF=L is used. 

(iamreg)) 

is one of the general registers 1 through 14 that contains the access 
method value in its low-order byte (bit positions 24 through 31). The 
high-order bytes are not inspected. This form may not be used when 
MF=L is coded. 

The use of amaddr and amreg should be restricted to those cases where the 
access method value has been generated previously by the MF=L form of 
DEBCHK. If MFssL is not coded, the significance of the AM operand 
depends upon the TYPE. 

If TYPE is ADD and AM is specified, the access method value is inserted in 
the DEBAMTYP field of the DEB, and all subsequent DEBCHK macros 
referring to this DEB must either specify the same AM or omit the operand. 
When the AM operand is omitted for TYPE= ADD, a null value (0) is placed 
in the DEB and all subsequent DEBCHK macros must omit the AM 
operand. 

If AM is specified when the TYPE is PURGE, DELETE, or VERIFY, the 

access method value is compared to the value in the DEBAMTYP field of 
the DEB. If AM is omitted, no comparison is made. 

BRANCH={NO|YES} 

specifies whether you want to use the branch entry to the DEBCHK verify 
routines. 

NO 

specifies branch entry is not to be used. The operands SAVREG, 
TCBADDR, and KEYADDR are ignored. 

YES 

specifies the branch entry is to be used. TYPE= VERIFY must be 
implicitly or explicitly specified. The operands TCBADDR and 
KEYADDR are reqmred. AM and MP are ignored. Notes for 
BRANCH=YES: 

• Registers 1, 2, 10, 11, 14, and 15 must not be used for 
SAVREG=. 

• Registers 1, 2, 10, 11, 14, 15, and the register specified for 
SAVREG= must not be used for cbaddr, TCBADDR=, or 
KEYADDR=. 

• The contents of registers 10, 11, and 14 are unpredictable on 
completion. Also, if you do not specify SAVREG=, the contents 
of register 2 are unpredictable. 

• At completion time, register 1 contains the address of the DEB, 
and register 15 contains either 0, 4, or 16 (see "Return Codes 
from the DEBCHK Macro" on page 155 for codes and their 
meanings). 
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TCBADDR=address — A-type address or (3-12) 

specifies the location or register containing the address of the TCB to be 
used by the DEBCHK verify routine. Use this operand only when 
BRANCH=YES. 

KEYADDR=a</^rm— A-type address or (3-12) 

specifies the location, or a register pointing to the location of a field 
containing the key to be used when accessing the DCB (or ACB). Use this 
operand only when BRANCH=YES. 

SAVREG=reg 

specifies the register in which register 2 is to be saved. Use this operand 
only when BRANCH=YES. 

MF=L 

indicates the list form of the DEBCHK macro instruction. When MF=L is 
coded, a parameter list is built consisting of the access method value that 
conesponds to the AM keyword. This value may be referenced by name in 
another DEBCHK macro by coding AM=:(aniaddr), or it may be inserted 
into the low-order byte of a register before issuing another DEBCHK macro 
by coding AM=((ainreg)). 



Return Codes from the DEBCHK Macro 



If the DEBCHK routine completes successfully, register 15 will be set to and 
register 1 will contain the address of the DEB when control is returned to your 
program. Otherwise, register 15 will contain one of the following decimal codes: 



Code Meaning 

04(X'04') Either (a) the DEB table associated with the job step does not exist; 
or (b) the DEBTBLOF field of the DEB was set to zero or a 
negative number, or was larger than the DEB table; or (c) register 1 
did not contain the same address as the DEB table entry. 

08(X'08') An invalid TYPE was specified. (The DEBCHK routine was entered 
by a branch, not by the macro.) 

1 2(X' OC ' ) Your program was not authorized and TYPE was not VERIFY. 

16(X' 10') DEBDCBAD did not contain the address of the DCB (or ACB) that 
was passed to the DEBCHK routine. 

20(X' 14' ) The AM value does not equal the value in the DEBAMTYP field. 

24(X' 18') The DEB is not on the DEB chain and TYPE=ADD was specified. 

28(X' IC ) TYPE= ADD was specified for a DEB that was akeady entered in 
the DEB table. 

32(X'20') The DEB table exceeded the maximum size (32760 bytes) and 
TYPE=ADD. 
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Purgiiig and Restoring I/O Requests 



The system's purge routines, guided by a parameter list you pass them, perform 
either a halt or a quiesce operation. In a halt operation, the purge routines stop the 
processing of specified I/O requests that were initiated with an EXCP macro 
instruction. In a quiesce operation, the purge routines: 

• Allow the completion of I/O requests that were initiated with an EXCP macro 
instruction and have been passed to the I/O supervisor for execution 

• Stop the processing of those requests that have not as yet been passed to the 
I/O supervisor, but save the lOBs of the requests so that they can be 
reprocessed (restored) later. 

The system's restore routines make it possible to reprocess I/O requests that are 
quiesced. {Note: Not covered here is the purge and restore processing that takes in 
I/O requests not initiated by an EXCP macro instruction. If you want to learn the 
full scope of purge and restore processing, see the I/O supervisor logic section of 
System Logic Library, Volume 8.) 

You can give control to the purge and restore routines in one of two ways: (1) by 
loading register 1 with the address of the parameter list and issuing specific SVC 
instructions or (2) by issuing the PURGE and RESTORE macro instructions. If 
your installation requires the use of macro instructions, you must add the macro 
definitions to the macro library (SYSl.MACLIB) or place them in a partitioned 
data set and concatenate this data set to the macro library. The macro definitions, 
JCL, and utility statements needed to add the macros to your macro library are 
presented in Figure 34 on page 157 and Figure 35 on page 158. Whether you 
issue the macro instructions or the SVC instructions, you must first build a 
parameter list. The SVC instructions are SVC 16 for PURGE and SVC 17 for 
RESTORE. 
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RESTORE Macro Definition 



gNAME 



SNAME 



,E1 



MACRO 

RESTORE 

AIF 

IHBINNRA 

SVC 

MEXIT 

IHBERMAC 

MEND 



SLIST 

CSLIST' EQ 
6LIST 
17 

01,150 



Control Statements Required 



") .El 

LOAD REG 1 

ISSUE SVC FOR RESTORE 

LIST ADDR MISSING 



//jobname 

//stepname 

//SYSPRINT 

//SYSUT2 

//SYSIN 

./ ADD 



JOB 

EXEC 

DD 

DD 

DD 



{parameters} 

PGM=IEBUPDTE , PARM=NEW 

SYSOUT=A 

DSNAME=SYS1 .MACLIB,DISP=OLD 

DATA 



NAME=RESTORE , LIST=ALL 



RESTORE macro definition 



./ ENDUP 
/* 

Figure 35. Macro Definirion, JCL, and Utility Statements for Adding RESTORE Macro to 
the System Macro Library 



PURGE — Halt or Finish I/O-Request Processing 

The macro instruction used to call the purge routines is coded as follows: 



[symbol] 
address 


PURGE 


parameter-list 



parameter list address — RX-type address, (2-12) or (1) 

address of a parameter list, 12 or 16 bytes long, that you have built on a 
fullword boundary in your storage. The parameter list address can be 
specified as an RX-type constant or in registers 2 through 12, or 1. 

The format and contents of the parameter list are as follows: 

Byte Contents 







A bjrte in which you specify what the purge routines will do. These are 
the bit settings and their meanings: 



I. 



Purge I/O requests to a single data set. 
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Either purge I/O requests associated with a TCB 

or address space, or purge I/O requests to more 
than one data set. 

.1 Post ECBs associated with purged I/O requests. 

. . 1 Halt I/O-request processing. (Quiesce 

I/O-request processing, if 0.) 

...1 .... Purge related requests only. (Valid only if a 

data-set purge is requested.) 

.... 0... Reserved — must be zero. 

1.. Do not purge the TCB request-block chain of 

asynchronously scheduled processing. 

1. Purge I/O requests associated with a TCB. 

1 This is a 16-byte parameter list. Additional purge 

options are specified in bytes 12 to 15. (If this bit 
is off, the list is 12 bytes long, and the purge 
routines do not put a return code in byte 4 of this 
list or in register 15.) 

1,2,3 The address of a DEB if you are purging I/O requests to a single data 

set. The address of the first DEB in a chain of DEBs if you are 
purging I/O requests to more than one data set. (The next-to-the-last 
word of each DEB must point to the next DEB in the chain; the 
second word of the last DEB must contain zeros.) 

4 A byte of zeros. (If bit 7 of byte is on, the purge routines will put a 

code in this byte: X'7F' if the purge operation is successful; X'40' if 
it is not successful. If bit 7 of byte is off, then X'7F' appears in this 
byte.) 

5,6,7 The address of the TCB associated with the I/O requests you want 

purged (but only if you turned on bit 6 of byte 0). May be zeros if the 
TCB is the one you are running under. 

8 Driver 10. (Default value of X'OO' implies that EXCP is the owner. 

9,10,1 1 The address of a word in your storage or the address of the 

DEBUSPRG field (which is X' 1 1 • bytes more than the DEB address 
in this parameter list). At whichever address you specify, the purge 
routines store a pointer to the purged I/O restore list, PIRL. In the 
PIRL is a pointer to the first lOB in the chain of lOBs. The location of 
the pointer and format of the chain are shown in Figure 36 on 
page 161. 

Note: This field is relevant for quiesce options only. 

12 A byte in which you can specify additional purge options. These are 

the bit settings and their meanings: 
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Note: The following applies only if bit 7 of byte is set to one. 

..1 Purge I/O requests associated with an address 

space. (You must be in supervisor state.) 

...1 .... Check the validity of all the DEBs associated with 

the purge operation if this is a data-set purge. 
Validate this parameter list, whatever the type of 
purge operation, by ensuring that there are no 
inconsistencies in the selection of purge options. 
(If you are in problem state, these actions are 
taken regardless of the bit setting.) 

....1... Ensure that I/O requests will be reprocessed 

(restored) under their original TCB. (If zero, and 
this bjrte is meaningful (bit 7 of byte is on), the 
I/O requests will be reprocessed under the TCB 
of the program making the restore request.) 

0.. Must be zero. 

13 A byte of zeros. 

14,15 The 2-byte ID of the address space associated with the I/O requests 

you want purged. (Only meaningful if bit 2 of byte 12 is on.) 

Control is returned to your program at the instruction following the PURGE macro 
instruction. 



Return Codes from PURGE Macro 



If the purge operation was successful, register 15 will contain zeros. Otherwise, 
register 15 will contain one of the following return codes: 



Code Meaning 

04(X'04' ) Your request to purge I/O requests associated with a 

given TCB was not honored because that TCB did not point 
to the job step TCB, as it must when the requestor is in 
problem state. 

08 (X ' 08 ' ) Either you requested an address-space purge operation, 
but were not in supervisor state, or you requested a 
data-set purge operation, but supplied no data-area address 
in bytes 1, 2, and 3 of the purge parameter list. 

20(X* 14') Another purge request has preempted your request. You 

may want to reissue your purge request in a time-controlled 
loop. 



Note: Register 15 will contain zeros, regardless of the outcome of the purge 
operation, if you set bit 7 in byte of the parameter list to zero. 
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Modifying the lOB Chain 



Note that, although this procedure is not recommended, if you want to change the 
order in which purged I/O requests are restored or prevent a purged request from 
being restored, you may change the sequence of lOBs in the lOB chain or remove 
an lOB from the chain. The address of the lOB chain can be obtained from the 
PIRL (see Figure 36). (The address of the PIRL is at the location pointed to by 
bytes 9 through 1 1 of the purge parameter Ust.) 



PIRL 





PIRRSTR 20(X'l^') 








Pointer to the first lOB. If Is, 
no I/O request was quiesced. 














— ► 


0B(1) 


(where 1 Is first lOB in chain) 









OBRESTR 25(19) 








Pointer to the next lOB in the 
chain. 




1 




1 









L 



lOB(n) 


(where n is last lOB in chain) 






OBRESTR 25(19) 






Contains binary Is. 











Figure 36. The PIRL and lOB Chain 



RESTORE— Reprocess I/O Requests 

The RESTORE macro is coded as follows: 



[symbol] 


RESTORE 


restore address 



restore address — RX-type address, (2-12) or (1) 

address you specified at byte 9 of the purge parameter list. 
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Performing Track Calculations 



The TRKCALC macro perf onns track capacity calculations. The standard, list, 
execute, and DSECT forms of the macro are described. Examples of the 
TRKCALC macro follow the macro descriptions. Using TRKCALC, you may do 
the following: 

• Perform track capacity calculations 

• Determine the number of records of a given size that can be written on a full 
track or on the remainder of a track 

• Perform track balance calculations as follows: 

— Determine whether a given record size can be written in the space 
remaining on the track and return the new track balance. 

— Determine the maximum size record that can be written on the track if the 
given record does not fit. 

— Determine the track balance if the last physical record is removed from the 
track. 



TRKCALC— Standard Form 

The format of the TRKCALC macro is: 



[symbol] 


TRKCALC 


FUNCTN=|TRKBAL 1 TRKCAPJ 

{,DEVTAB=addr \ ,UCB=addr | ,TYPE=a^/i 

[,BALANCE=a^^rl 

[,REMOVE=|YES | NO}] 

[,MAXSIZE={YES | NO}] 

{,RKDD=addr | ,R=addr,K=addr,DD=addfi 

[,REGSAVE=|YES | NO}] 

r,MF=Il 



FUNCTN=|TRKBAL | TRKCAP} 

specifies the function to be performed. 

Note: You must specify one of the three keywords, DEVTAB, UCB, or 
TYPE, to provide the macro a source for information. 

TRKBAL 

if REMOVE=NO is specified, TRKBAL calculates whether an 
additional record fits on the track and what the new track balance 
would be if the record were added. If REMOVE=YES is specified, 
TRKBAL calculates what the track balance would be if a record were 
removed from the track. The record to be added or removed from the 
track is defined by the RKDD parameter, or by the R, K, and DD 
parameters. 
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If R=l (or the R value in the RKDD parameter is 1) and 
REMOVE=NO is specified, record 1 is added to an empty track; if 
R— 1 and REMOVE= YES is specified, record 1 is deleted from the 
track, leaving an empty track. 

If R^fcl, the specified record is added to or removed from the track. 
The input track balance may be supplied through the BALANCE 
parameter; if it is not supplied, it is assumed that the track contains 
equal-sized records as specified in the RKDD parameter (or in the R, 
K, and DD parameters). 

When REMOVEs=NO is specified, one of the following occurs: 

• If the record fits on the track, register contains the new track 
balance. 

• If the record does not fit on the track and MAXSIZE=NO is 
specified, a "record does not fit" return code is given in register 
15. 

• If the record does not fit and MAXSIZE=YES is specified, one of 
the following happens: 

— The data length of the largest record that fits in the remaining 
space is returned in register 0. 

— A code is returned that indicates no record fits in the 
remaining space. 

When REMOVE=YES is specified, one of the following occurs: 

• If R= 1 , register contains the track capacity. 

• If K-^ 1 , registers contains the input track balance (supplied 
through the BALANCE parameter) incremented by the track 
balance used by the input record. If the input balance is not 
supplied, register contains the track capacity left after R— 1 
records are written on the track. 

TRKCAP 

calculates, and returns in register 0, the number of fixed-length 
records that may be written on a whole track (R= 1) or on a partially 
filled track (R?^!). The records are defined by the K and DD values 
of the RKDD parameter, or by the K and DD parameters. 

One of the following occurs: 

• If R= 1, the BALANCE parameter is ignored and the calculation 
is made on an empty track. 

• If R^ 1 and the BALANCE parameter is omitted, the calculation 
is made for a track that already contains R— 1 records of the 
length defined by the K and DD values. 
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• If R96 1 and the BALANCE parameter is supplied, the calculation 
is made for a track whose remaining track balance is the value of 
the BALANCE parameter. 

DEVTAB=adi/r— RX-type address, (2-12), (0), (14) 

addr specifies a word that contains the address of the device characteristics 
table entry (DCTE). If you specif y a register, it contains the address of the 
DCTE, not the address of a word containing the address of the DCTE. The 
address of the DCTE can be found in the DCBDVTBA field of an opened 
DCB. 

IJCB^addr—RX-type address, (2-12), (0), (14) 

addr specifies the address of a word that contains the address of the UCB. If 
you specify a register, it contains the address of the UCB, not the address of 
a word containing the address of the UCB. You must ensure that the UCB 
address is valid by verifying that byte 3 (UCB +2) in the UCB contains 
X'FF'. 

TYPE=a(/(//-— RX-type address, (2-12), (0), (14) 

you may specify the address of the UCB device type (UCBTBYT4), or you 
may specify the 1-byte UCB device type in the low-order byte of a register. 

BALANCE=flJJr— RX-type address, (2-12), (0), (14) 

you may specify either the address of a halfword containing the current track 
balance, or you may specify the balance in the low-order two bytes of a 
register. The value supplied may be the value returned when you last issued 
TRKCALC. If R= 1 , the balance is reset to track capacity by TRKCALC, 
and your supplied value is ignored. This is an input value and is not modified 
by the TRKCALC macro. The resulting track balance is returned in register 
and in the TRKCALC parameter list field STARBAL. 

REMOVE={YES|NO} 

indicates if a record is to be deleted from the track. 



YES 



NO 



specifies that the record identified by the record number (specified in 
the R kejnvord) is being deleted from the track. The track balance is 
incremented instead of decremented. 

Note: YES is vaUd only on a FUNCTN=TRKBAL caU. 



specifies that a record is not to be deleted from the track. NO is the 
default. 



MAXSIZE={YES|NO} 
YES 



If the specified record does not fit, the largest length of a record with 
the specified key length that fits is returned (register 0). 

Note: YES is valid only on a FUNCTN=TRKBAL call. 
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NO 

Maximum size is not returned. NO is the default. 



RKDD=a</^r— RX-type address, (2-12), (0), (14) 

addr specifies a word containing a record number (1 byte), keylength (1 
byte), and data length (2 bytes) (bytes 0, 1, and 2 and 3, respectively) or a 
register containing the record number, key length, and data length. R, K, 
and DD may be specified by this keyword, or you may use the following 
three keywords instead. 

R=addr'—RK'type address, (2-12), (0), (14), or n 

you may specify either the address of the record number, or you may specify 
the record number using the low-order byte of a register or immediate data 
(n). Specify a decimal digit for n (immediate data). 

K=a<i^r— RX-type address, (2-12), (0), (14), or n 

you may specify either the address of a field containing the hexadecimal 
value of the record's key length, or you may specify the record's key length 
using the low-order byte of a register or immediate data (n). Specify a 
decimal digit for n (immediate data). 

DD=af/^r— RX-type address, (2-12), (0), (14), or n 

you may specify either the address of a field containing the hexadecimal 
value of the record's data length, or you may specify the record's data length 
using the low-order two bytes of a register or inunediate data (n). Specify a 
decimal digit for n (immediate data). 

REGSAVE={YES | NO} 

YES 

specifies registers 1 through 14 are saved and restored in the 
caller-provided save area (pointed to by register 13) across the 
TRKCALC call. Otherwise, registers 1, 9, 10, 11, and 14 are 
modified. Registers and 15 are always modified by a TRKCALC 
caU. 



NO 



specifies registers are not saved across a TRKCALC call. NO is the 
default. 



MF=I 

specifies storage definition for the TRKCALC parameter list and parameter 
list initialization, using the given keywords, then calling the TRKCALC 
function. MF=I is the default. 



TRKCALC — ^Execute Form 



A remote parameter list is referred to and can be modified by the execute form of 
the TRKCALC macro. The TRKCALC routine is called. The description of the 
standard form of the macro provides the explanation of the function of each 
operand. 
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[symboll 


TRKCALC 


[FXJNCTN=|TRKBAL | TRKCAPH 

[{,DEVTAB={addr\*\\ 
,UCB=|atWr | *} \ ,TYPE={a^r | *}}] 
lBALASCE={addr [*}] 
I,REMOVE=|YES | NO^ 
[,MAXSIZE={YES | NO}l 
[{,RKDD=^addr\,R=addr,K=^addrJ}D^addri] 
[,REGSAVE={YES | NO« 
,MF=s(E,aJ</r) 



FUNCTN=|TRKBAL | TRKCAI^ 

is coded as shown in the standard f onn. If this ke3rword is omitted, any 
specification of REMOVE, MAXSIZE, LAST, and the RX form of 
BALANCE is ignored. In addition, DEVTAB is assumed if UCB is coded 
and a failure occurs, or if TYPE is specified. When you use FUNCTN, one 
of the keywords (DEVTAB, UCB, or TYPE) must be specified to provide an 
information source. 

DEVTAB=flJf/r I *— RX-type address, (2-12), (0), (14) 

is coded as shown in the standard form except for the * subparameter. 
Specify an * when you have inserted the address of the device characteristics 
table entry (DCTE) in the parameter list. 

VCB:^addr \ *— RX-type address, (2-12), (0), (14) 

is coded as shown in the standard form except for the * subparameter. 
Specify an * when you have inserted the address of the UCB in the 
parameter list. 

TYPE=aJt/r I *— RX-type address, (2-12), (0), (14) 

is coded as shown in the standard form except for the * subparameter. 
Specify an * when you have inserted the address of the UCB type 
(UCBTYP) in the parameter list. 

BALANCE=aJi/r I ♦—RX-type address, (2-12), (0), (14) 

is coded as shown in the standard form except for the * subparameter. 
Specify an * when you have inserted the balance in the parameter list. 

REMOVE=[YES|NO} 

is coded as shown in the standard form. 

MAXSIZE^IYES | NO} 

is coded as shown in the standard form. 

RKDD=fl^r— RX-type address, (2-12), (0), (14) 
is coded as shown in the standard form. 

R=addr—RX-iype address, (2-12), (0), (14) or n 
is coded as shown in the standard form. 

K=addr— RX-type address, (2-12), (0), (14), or n 
is coded as shown in the standard form. 
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DD=fl^Jr— RX-type address, (2-12), (0), (14), or n 
is coded as shown in the standard fonn. 

REGSAVE=|YES | NO? 

is coded as shown in the standard form. 

MF=iE,addr) 

This operand specifies that the execute form of the TRKCALC macro 
instruction and an existing data management parameter Ust are used. 

E 

Coded as shown. 

fl<i^r— RX-type address, (0), (1), (2-12), or (14) 

specifies an in-storage address of the parameter list. 



TRKCALC— List Form 



The list form of the TRKCALC macro constructs an empty, in-line parameter list. 
By coding only MF=L, you construct a parameter list, and the actual values can be 
supplied by the execute form of the TRKCALC macro. Any parameters other than 
MF=L are ignored. 



[symbol] 


TRKCALC 


MF=L 



TRKCALC— DSECT Only 



This call gives a symbolic expansion of the parameter Ust for the TRKCALC 
macro. No DSECT statement is generated. If a name is specified on the macro 
call, it applies, after any necessary boundary alignment, to the beginning of the list. 
The macro-generated symbols all begin with "STAR". 



[symboll 


TRKCALC 


MF=D 



Input Register Usage for All Forms of MF 

Registers 0, 2 through 12, and 14 are available to provide input for ke3rwords. 

Register 1 is used only to provide the address of the parameter list for an MF=E 
caU. 

Register 13 may be used as input for keywords, if REGSAVE=YES is not 
specified. 

Register IS is used as a work register to build the TRKCALC parameter list for the 
MF=E call; it is not available as an input register. 
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Output from TRKCALC 

FUNCTN=TRKBAL 



Register 15^0 

The record fits on the track. Register and STARBAL contain the 
new track balance. 

Register 15=4 

Record does not fit on the track. If MAXSIZE= YES is specified, a 

partial record does not fit either. Register and STARBAL are set to 
zero. 

Register 15=8 

Record does not fit on the track. MAXSIZE=YES is specified, and a 
partial record does fit. Register and STARBAL are set to the 
maximum number of data bytes that fit on the remainder of the track 
with the specified keylength. 

Note: The keylength is excluded from the count of maximum data 
bytes. 

STARBAL 

This is the track balance field of the TRKCALC parameter list. This 
field is first set to the track capacity if R^ 1, or to the supplied 
BALANCE value if R/1, or to the calculated balance if R^fcl and 
BALANCE are omitted. STARBAL is updated to the new track 
balance if the record fits; otherwise, STARBAL is left with the input 
track balance value. 

FUNCTN=TRKCAP 

Register 15=0 

Register contains the number of records that fit on the track if R = 
1, or the number of records that fit on the remainder of the track if R 

Register 15=4 

No records of the length specified fit on a full track (R = 1) or a 
partial track (R ?£ 1). Register is set to zero. 

STARBAL 

This is the track balance field of the TRKCALC parameter list. This 
field is first set to the track capacity if R= 1, or to the supplied 
BALANCE value if R?* 1, or to the calculated balance if R/ 1 and 
BALANCE are omitted. 
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Return Codes from TRKC ALC 



The TRKC ALC macro passes a return code in register IS. The return codes and 
their meanings are as follows: 



Contents Meaning 

OO(X'OO') Indicates that register contains the new track balance 

04(X'04') Indicates that the record did not fit (register « 0) 

08(X'08') Indicates that the record did not fit (Register contains the maximum 
data length that does fit) 



TRKCALC Macro Examples 



In this example, TRKCALC is coded to determine how many records of a given 
size with 10-byte keys fit on an IBM 3380 track. After issuing the macro, the 
number of records is saved in NUMREC: 

TRKCALC FUNCTN=TRKCAP , TY PE=UTYPE , R= 1 , K= 1 , DD=DL , MF= ( E , ( 1 ) ) 
ST 0, NUMREC SAVE NUMBER OF RECORDS 



DL 


DC 


H ' xxxx • 


DATA LENGTH 


UTYPE 


DC 


X'OE' 




NUMREC 


DS 


F 


MAX # OF RECORDS 



In this example, TRKCALC is coded to determine whether another record can fit 
on a track of a 3380, given a track balance. 

TRKCALC FUNCTN=TRKBAL , TYPE=UTYPE , R=REC , K=KL , DD=DD , BALANCE=BAL , 
MAXSIZE=YES,MF=(E, (1)) 



UTYPE DC X ' OE ' 

REC DC X ' XX ' 

KL DC X ' XX ' 

DD DC H • xxxx ' 

BAL DC H'xxxx' 
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Releasing Unused Space from a DASD Data Set 



Direct Access Device Storage Management (DADSM) supports the release of 
unused space that is allocated to sequential or partitioned data sets.'* This partial 
release function is called when: 

• The data set is closed (if the RLSE subparameter of SPACE was specified on 
its DD card). 

• A restart is processing from a checkpoint in which the data set was extended 
after a checkpoint. 

• A PARTREL macro is issued. 



The PARTREL Macro 



The PARTREL macro builds a parameter list and issues a LOAD, BASSM, 
DELETE sequence. This sequence partially releases the space allocated to a data 
set without an associated OPEN/CLOSE. 

The PARTREL macro supports sequential and partitioned data sets on volumes 
with or without an indexed VTOC. The macro may be coded in the execute, 
DSECT, and list forms, but not the standard form. The calling program: 

Must be APF authorized. 

Must have allocated the volume to this task and must ensure it stays mounted 
during the PARTREL function. 



Must ensure that the data set is not open. 

Must not hold any locks. 

Must provide the address of an available standard register save area in general 
register 13. 

Must provide the associated parameter list and parameters in storage below 16 
megabytes virtual. 

May be in any storage key. 

May run in either supervisor or problem program state. 

May include the CVAFTBL mapping macro ICVAFPRM, and test the 
CVFDFPFT field. If the CVFPREL bit is on, PARTREL is supported as 
described. 



^ The format- 1 DSCB for the data set contains an identifier (DSILSTAR) for the last 
data record written. 
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PARTREL— Execute Form 

The execute form of the PARTREL macro is as follows: 



[symbol] 


PARTREL 


MF={(E,fl^r) 1 (E,(reg))} 
UDSN^{addr\ireg))}] 
l,ERASE=|YES | NO | lESTU 
l,MODE={PGM 1 SUPH 
I,TIOT={ENQ 1 NOENQJl 
[,UCB=(reg)l 



Except for MODE, all parameters default to the current contents of the parameter 
list. The MODE parameter defaults to PGM. 

To provide a better understanding of these parameters, their descriptions include 
information about DADSM execution-time processing. These descriptions use the 
term "effective value" to designate the value used by DADSM for this request. 
The effective value may be: 

• Specified as a parameter on the PARTREL macro. 

• Provided as the parameter's associated value in the parameter list. 

• Defined by DADSM from the information provided in the request. 

MF={(E,arfrfr)|(E,(reg))} 

specifies the execute form of the macro and the address of an existing 
PARTREL parameter list. 



addr—RX-type address, (reg) — (0-12) 

specifies the PARTREL parameter list address. 



DSN={addr\(reg))] 

specifies the address of a 44-byte area that contains the data set name. The 
data set name must be left-justified, with any unused bytes defined as 
blanks. 

a^Jr— RX-type address, (reg)—(0), (2-12) 

You must provide an effective value for DSN. 

ERASE= {YES | NO | TESTJl 

specifies a residual data erase attribute (see "Deleting a Data Set from the 
VTOC (SCRATCH and CAMLST SCRATCH)" on page 33 for a 
description of erase attributes). ERASE=YES and ERASE=NO are 
mutually exclusive. The default is ERASE=TEST. 

ERASE^YES 

specifies that the area being released should be erased (overwritten 
with zeros) before it is made available for new allocations. 

ERASE=NO 

specifies that the area should not be erased. This specification 
overrides and RACF erase attribute. 
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ERASEsTEST 

specifies that the associated RACF erase attribute is to be used. 



MODE^fPGMlSUPJ 

specifies that PARTREL is requested by a caller in problem program state 
(MODE=bPGM) or in supervisor state (MODE=SUP). MODE=PGM is the 
default. 

If the calling program is m supervisor state (and wants to be returned in 
supervisor state), the effective value of MODE must be SUP. If the calling 
program is in problem program state, the effective value of MODE must be 
PGM. 

TIOT={ENQ I NOENQ}! 

specifies the desired SYSZTIOT and SYSDSN ENQ processing within partial 
release. The default is ENQ. 

TIOT=ENQ 

specifies that partial release is to do its normal, exclusive ENQ on 
SYSZTIOT and SYSDSN. If either of these ENQ requests fails, 
PARTREL will terminate the request with a return code of X'08'. 

TIOT=NOENQ 

specifies that the caller has provided the necessary serialization. If 
partial release finds that the caller does not have exclusive use of 
SYSDSN, PARTREL will terminate the request with a return code of 
X'08'. 

UCB=(reg) 

specifies the address of the UCB for the volume on which the subject data 
set resides. The volume must be mounted, and you must ensure that it 
remains mounted. 

iregy-(0), (2-12) 

You must provide an effective value for the UCB parameter. 



PARTREL— List Form 



The list form of PARTREL is specified as follows: 



[symboll 


PARTREL 


MF=L 
[,DSN*a^rl 

[,ERASE»{YES | NO | lESTH 
[,MODE=|PGM 1 SUHJ 
l,TIOT=={MQ 1 NOENQn 



1 72 MVS/XA System-Data Administration 



Notes: 

1. The execute form of the UCB parameter can not be specified on the list form. 

2. The list form MODE parameter is for documentation only. The effective value of 
MODE is as specified or defaulted on the execute form. 



For an explanation of the parameters, see the execute form. 
An example of the list form's expansion is: 



PRELPL 


PARTREL MF=L 


+PRELPL 


DS OF 


+ 


DC CL4 • PREL ' 


+ 


DC AL2 ( PRL 1 E-PRELPL ) 


+ 


DC H ' • 


+ * 




+ 


DC XLI'OO' 


+ 


DC XL3'00' 


+ 


DC A(0) 


+ 


DC A(0) 


+PRL1E 


EQU * 



EBCDIC 'PREL' FOR PARTREL 
LENGTH OF PARAMETER LIST 
ERROR CODE RETURNED FROM 

PARTIAL RELEASE 
PARAMETER FLAG BYTE 
RESERVED 

ADDRESS OF DATA SET NAME 
UCB POINTER 
END OF PARAMETER LIST 



PARTREL— DSECT Form 

The DSECT form of PARTREL is specified as follows: 



[symbol] 


PARTREL 


MF=D 



An example of the DSECT form's expansion is: 



PRELPL 


PARTREL MF=D 


+PRELPL 


DSECT 




+PRLPLID 


DS 


CL4 


+PRLNGTH 


DS 


AL2 


+PRERRCDE 
+ * 
+PRLFLAG 


DS 


H 


DS 


XL1 


+PRLPGM 


EQU 


X'OO' 


+PRLSUP 


EQU 


X'80' 


+PRLTIOT 


EQU 


X'40' 


+PRLNERAS 


EQU 


X'20' 


+PRLERASE 


EQU 


X'10' 


+PRLFRES 


EQU 


X'OF.' 


+PRLRSVD 


DS 


XL3 


+PRLDSN 


DS 


A 


+PRLUCB 


DS 


A 


+PRLEND 


EQU 


* 


+PRLENGTH 


EQU 


PRLEND-PRELPL 



DSECT FOR PARAMETER LIST 
EBCDIC 'PREL' FOR PARTREL 
LENGTH OF PARAMETER LIST 
ERROR CODE RETURNED FROM 

PARTIAL RELEASE 
PARAMETER FLAG BYTE 
MODE=PGM (PROBLEM PROGRAM) 
MODE=SUP (SUPERVISOR STATE) 
TIOT=NOENQ 
ERASE=NO 
ERASE=YES 
RESERVED 
RESERVED 

DATA SET NAME POINTER 
UCB POINTER 
END OF PARAMETER LIST 
LENGTH OF PARAMETER LIST 
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Return Codes From PARTREL 



Control returns to the instruction following the last instruction generated by the 
PARTREL macro. If the data set was successfully processed, register IS contains 
zeros. Otherwise, register 15 contains one of the following return codes. This is a 
cumulative list of DADSM partial release return codes. Some of these codes may 
not apply to the PARTREL macro. 



Code Meaning 

02(X ' 02 ' ) Unable to find extent in format- 1 DSCB. 

04(X ' 04 • ) Unable to find extent in f ormat-3 DSCB. 

08(X'08') Either the required SYSZTIOT or SYSDSN ENQ faUed, or an 

unrelated DEB indicates that another DCB is open to the data set. 

12(X'0C') Invalid parameter list. 

1 6(X' 10' ) Permanent I/O error or unexpected CVAF error return code or 
installation exit rejected the request. 

20(X • 1 4 • ) DSN, or DSN pointer is invalid. 

24(X' 1 8 ' ) InvaUd UCB pomter. 

28(X' 1 C • ) Given DSORG is not supported. 

32(X' 20' ) No room m the VTOC. 



Allocating a DASD Data Set 



The REALLOC macro builds a parameter list and issues an SVC 32 to allocate a 
new data set. You can code the macro in the execute, DSECT, and list forms, but 
not in the standard form. The calling program: 

Must be APF authorized. 

Must have allocated the volume to this task and must ensure it wUl stay 
mounted during the REALLOC function. 

Must not hold any locks. 

Must provide the associated parameter list and parameters in storage below 
16-megabyte virtual. 

May use any storage key. 

May run in either supervisor or problem program state. 
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• Must note that REALLOC does not call RACF or catalog management. 

• May include the CVAFTBL mapping macro ICVAFPRM, and test the 
CVFDFPFT field: 

— If the CVFPREL bit is on, REALLOC is supported as it is documented in 
this release. 

— If the CVFPREL bit is off and the CVFREALL bit is on, REALLOC is 
supported as documented in a prior release. (Absolute allocation is not 
supported.) 

— If neither bit is on, REALLOC is not supported. 

The calling program must provide the REALLOC macro with one or more model 
DSCBs. You can use the OBTAIN macro to get the DSCBs from other data sets 
and modify them for the request. DADSM uses these model DSCBs to validate the 
allocation request, and to construct those DSCBs that are written to the VTOC for 
the requested allocation. 

The ALLOC parameter for the REALLOC macro defines the allocation request as 
either absolute (ABS) or movable^ (MOV). 

An absolute request provides a set of allocation parameters, a full format- 1 DSCB, 
an optional format-2 DSCB, and an optional format-3 DSCB that describe the 
attributes of the desired data set: 

• Support is provided for data sets with a user label extent and for ISAM data set 
allocations,^ but is not limited to these two types. 

• The number of extents to be allocated, and their absolute placement on the 
volume, are defined by the format- 1 DSCB and one (optional) format-3 
DSCB. 

An absolute request is limited to a single volume with indexed VTOC support. 

A movable request provides a set of allocation parameters and a partial DSCB'' that 
describe the attributes of the desired data set: 

• Data sets with a user label extent, ISAM data sets, and absolute track allocated 
data sets are not supported. 



5 



The requested data set's allocation is not sensitive to its placement on the volume. 
This is specifically NOT a reference to the format-1 DSCB bit DSIDSGU (unmovable 
bit), which may be either on or off in an ALLOCa=MOV request's partial DSCB. That 
is, the data set may subsequently contain location-dependent information. 

See the description of the F2DSCB parameter in the REALLOC macro execute form 
for more information. 

The partial DSCB (mapped by the lECFDSCB macro) consists of the first 98 bytes of 
a format-1 DSCB foUowed by two full words: PDPRIQTY (primary space request in 
tracks), and PDDIRQTY (number of directory blocks). 
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• The maximum number of extents that may be allocated is determined by the 
data set organization (PDIDSORG) and the data set indicator (PDIDSIND) 
bytes in the partial DSCB. If PDIDSORG indicates a VSAM data set 
organization and PDIDSIND indicates that the data set is cataloged in an 
Integrated Catalog Facility catalog, the maximum number of extents is 123. 
Otherwise, the maximum number of extents is 16. 

A movable request is limited to a single volume with or without indexed VTOC 
support. 

REALLOC — Execute Form 

The format of the REALLOC macro in execute form is: 



[symbol] 


REALLOC 


MF=KE,fl^r) 1 iE,(reg))} 
{,ALLOC=|ABS|MOV}} 

[,DSSIZE={a^r|(re^)}l 

UF2DSCB={addr\(regm 

UF3DSCB={addr\(reg)}] 

UMlNAV={addr\(reg)}] 

lPDSCB=>{addr\(reg)}] 

l,PDSDIR*{fltWr|(re^)}| 

llJCB=(reg)] 



All parameters except ALLOC default to the current contents of the referenced 
parameter list. The ALLOC parameter defaults to MOV. 

To provide a better understanding of this macro's parameters, their descriptions 
include information about DADSM execution-time processing. These descriptions 
use the term "effective value" to designate the value used by DADSM for this 
request. The effective value may be: 

• Specified as a parameter for the REALLOC macro. 

• Provided as the parameter's associated value in the referenced parameter list. 

• Defined by DADSM from information provided in the request. 

MF=m^ddr\iE,(reg))} 

specifies the execute form of the macro and the address of a REALLOC 
parameter list. 

addr — RX-type address, (reg) — (0-12) 

specifies the address of the REALLOC parameter list. 

ALLOC={ABS\ MOy\ 

specifies that the REALLOC request is for absolute extents 
(ALLOC=ABS) or for a movable allocation (ALLOC=MOV). 
ALLOC =MOV is the default. 

If you want absolute allocation, the effective value of ALLOC must be ABS. 

DSSlZE={addr\(reg)] 

specifies the size of the data set to be allocated in tracks. The DSSIZE 
parameter is invalid for an ALLOC=sABS request. 
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addr — ^RX-type address 

specifies the address of a full word that contains the data set size. 

(reg)— (0), (2-12) 

specifies a register that contains the size of the data set. 

You must provide an effective value for DSSIZE for an ALLOC = MOV 
request. The PDPRIQTY field of the partial DSCB is ignored. 

DADSM assumes that you have provided the effective value of DSSIZE in 
tracks even if the PDISCALO flag byte of the partial DSCB indicates a 
cylinder request, X' CO', or an average block request, X'40'. 

If the PDISCALO flag byte of the partial DSCB indicates a cylinder request, 
X' CO', or an average block with round request, X'41 ', the effective value of 
DSSIZE is rounded up to the next fuU cylinder. 

F2DSCB={a^^r|(r^g)} 

specifies the in-storage address of a format-2 DSCB. This DSCB is used as 
a model to construct the allocated data set's format-2 DSCB. 

The F2DSCB parameter is invalid for an ALLOC=MOV request. 

a^r— RX-type address, (reg) — (0), (2-12) 



You may provide an effective value for F2DSCB in an ALLOC =ABS 
request when the DSIDSORG flag byte of the given format- 1 DSCB is 
X'80' (indexed sequential organization). 

Because REALLOC allocates on the basis of a single volume for each 
request and because a multivolume ISAM data set is defined with one 
format-2 DSCB (on the first volume only), the associated DADSM 
allocation processing routines do not require a format-2 DSCB (that is, 
multiple REALLOC requests may be used to to allocate a multivolume 
ISAM data set). 

F3DSCB=|a^^r|(reg)} 

specifies the in-storage address of a format-3 DSCB. This DSCB is used as 
a model to construct the allocated data set's format-3 DSCB. 

The F3DSCB parameter is invalid for an ALLOC=MOV request. 

o^t/r— RX-type address, (reg) — (0), (2-12) 



You must provide an effective value for F3DSCB in an ALLOC =ABS 
request when the DSINOEPV byte of the format- 1 DSCB indicates more 
than three extents (or when the DSINOEPV byte indicates more than two 
extents and the DSIEXTI extent type indicator is X' 40'; a user label 
extent). 

The REALLOC request is limited to a maximum of 16 extents. No more 
than one format-3 DSCB can be specified. 
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You must provide an effective value of zero for the F3DSCB in an 
ALLOC=ABS request when the DSINOEPV byte of the format-l DSCB 
indicates that there are less than four extents (or when the DSINOEPV byte 
indicates that there are less than three extents and the DSIEXTI extent type 
indicator is X' 40*; a user label extent). 

MTNAV={addr\ireg)} 

specifies the size of the minimum allocation unit in tracks. All primary 
extents for this data set are in multiples of this minimum allocation unit. 
This minimum does not apply to subsequent extensions of the data set. 

The MINAU parameter is invalid on an ALLOC =ABS request. 

addr — RX-tjrpe address 

specifies the address of a full word containing the minimum allocation 
unit. 

iregh-(0), (2-12) 

specifies a register containing the minimum allocation unit. 

The MINAU parameter has no effect on the requested allocation if: 

• You provide an effective value of zero. 

• The PD 1 SC ALO flag byte of the partial DSCB indicates either a 
cylinder request, X' CO*, or an average block with round request, X*41'. 

Otherwise, the effective value of DSSIZE must be a multiple of the effective 
value of MINAU. 

PDSCB^{addr\ireg)} 

specifies the address of a partial DSCB (for ALLOC=MOV) or the 
in-storage address of a full format-l DSCB (for ALLOC=ABS). This 
DSCB is used as a model to construct the allocated data set's format-l 
DSCB. 

o^r-— RX-type address, (reg) — (0), (2-12) 



You must provide an effective value for the PDSCB parameter. 

PDSDlR^{addr\ireg)] 

specifies the number of 256-byte directory blocks for a partitioned data set 
(PDS). 

addr- — ^RX-type address 

specifies an in-storage address of a full word containing the number of 
256-byte PDS directory blocks. 

(reg)— (0), (2-12) 

specifies a register containing the number of 256-byte PDS directory 
blocks. 

You must provide an effective value for PDSDIR when partitioned 
organization is indicated: 
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. The DS 1 DSORG flag byte of the format- 1 DSCB is X • 02 ' 

(ALLOC=ABS). 
• The PD 1 DSORG flag byte of the partial DSCB is X ' 02 ' 

(ALLOC=MOV). 

For an ALLOC = MOV request, you can specify the effective value of 
PDSDER in the PDDIRQTY field of the partial DSCB. The PDDIRQTY 
field is used if and only if, the effective REALLOC parameter list value of 
PDSDIR is zero. 

Do not specify an effective value for PDSDIR when a PDS is not indicated. 

UCB=(reg) 

specifies the address of the UCB for the volimie in which the data set is to be 
allocated. The volume must be mounted, and you must ensure that it 
remains mounted. 

(reg)—iO\ (2-12) 



You must provide an effective value for the UCB parameter. 



REALLOC— List Form 



The list form of the REALLOC macro is specified as follows: 



[symbol] 


REALLOC 


MF=L 

l,ALLOC={ABS 1 MOVn 
[,¥2DSCB=addr\ 
l¥3DSCB=addr\ 
l,PDSCB=fl^rl 



Notes: 

1. The execute form parameters DSSIZE, MINA U, PDSDIR, and UCB can not be 
specified on the list form. 

2. The list form 's ALLOC parameter affects the tests made by the REALLOC 
macro at assembly time and the contents of the parameter list. 

3. The effective value of ALLOC is as specified or defaulted on the execute form. 
See the execute form for an explanation of the parameters. 

An example of the list form expansion is: 
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REALPL REALLOC MF=L 



+REALPL DS 



OF 



+ 


DC 


CL4 • REAL • 


+ 


DC 


AL2 (RAL1E-REALPL) 


+ 


DC 


H'O' 


+* 






+ 


DC 


XLI'OO' 


+ 


DC 


XLS '00' 


+ 


DC 


F'O' 


+ 


DC 


F'O' 


+ 


DC 


A{0) 


+ 


DC 


A(0) 


+ 


DC 


F'O' 


+ 


DC 


A(0) 


+ 


DC 


A{0) 


+RAL1E 


EQU 


* 



EBCDIC 'REAL' FOR REALLOC 
LENGTH OF PARAMETER LIST 
ERROR CODE RETURNED FROM 
ALLOCATE (SVC 32) 
PARAMETER FLAG BYTE 
RESERVED 
DATA SET SIZE 
MINIMUM ALLOCATION UNIT 
PARTIAL DSCB POINTER 
UCB POINTER 
PDS DIRECTORY QUANTITY 
FORMAT 2 DSCB POINTER 
FORMAT 3 DSCB POINTER 
END OF PARAMETER LIST 



REALLOC— DSECT Only 

The DSECT form of REALLOC is specified as follows: 



[symboll 


REALLOC 


MF=D 



An example of the DSECT form expansion is: 



REALPL 


REALLOC MF=D 


+REALPL 


DSECT 




+RALPLID 


DS 


CL4 


+RALNGTH 


DS 


AL2 


+RAERRCDE 


DS 


H 


+RALFLAG 


DS 


XL1 


+RALMOV 


EQU 


X'OO' 


+RALABS 


EQU 


X'80' 


+RALFRES 


EQU 


X'7F' 


+RALRSVD 


DS 


XL3 


+RALDSSZ 


DS 


F 


+RALMAU 


DS 


F 


+RALPDSCB 


DS 


A 


+RALUCB 


DS 


A 


+RALDQTY 


DS 


F 


+RAL2DSCB 


DS 


A 


+RAL3DSCB 


DS 


A 


+RALEND 


EQU 


* 


+RALENGTH 


EQU 


RALEND-REALPL 



DSECT FOR PARAMETER LIST 
EBCDIC 'REAL' FOR REALLOC 
LENGTH OF PARAMETER LIST 
ERROR CODE RETURNED FROM 

ALLOCATE (SVC 32) 
PARAMETER FLAG BYTE 
ALLOC=MOV 
ALLOC=ABS 
RESERVED 
RESERVED 
DATA SET SIZE 
MINIMUM ALLOCATION UNIT 
PARTIAL DSCB POINTER 
UCB POINTER 
PDS DIRECTORY QUANTITY 
FORMAT 2 DSCB POINTER 
FORMAT 3 DSCB POINTER 
END OF PARAMETER LIST 
LENGTH OF PARAMETER LIST 
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Return Codes from REALLOC 



Control returns to the instruction following the SVC 32 generated by the 
REALLOC macro. If the data set was successfully allocated, register 15 contains 
zeros. Otherwise, register 15 contains one of the following return codes: 

Note: This is a cumulative list of DADSM allocation return codes. Some of these 
codes may not apply to the REALLOC macro. 



Return Reason 

Code (R15) Code (RO) 

004(X'04') 



008(X'08') 
012(X'0C') 



016(X'10') 
020(X'14') 
024(X'18') 
028(X'1C') 

032(X'20') 
036(X'24') 

040(X'28') 

044(X'2C') 

048(X'30') Ol(X'Ol') 
02(X'02') 
03(X'03') 



Meaning 

Data set name of request already exists on this 
volume. Initial allocation not possible under the 
name given. 

No room available m the VTOC or VTOC index. 

One of the following errors was encountered: 

• Permanent I/O error 

• Error returned by CVAF 
Requested absolute track not available. 
Requested quantity not available. 

Average record length greater than 65535 bytes. 

Incorrect DSORG or DISP in an ISAM mdex 
request. 

No prime area requested for ISAM data set. 

ISAM prime area must be requested before 
overflow. 

Space requested must begin on a cylinder 
boundary. 

Duplicate ISAM DSNAME element. 

Invalid REALLOC parmlist ID. 

Invalid REALLOC parmlist length. 

REALLOC request, but neither ALLOCs=ABS nor 
ALLOC=MOV is specified. 
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Return 
Code (R15) 



052(X'34' 
056(X'38' 

060(X'3C 

064(XM0' 
068(X'44' 
072(X'48' 
076(X'4C' 

080(X'50' 
084(X'54' 
088(X'58V 
092(X'5C' 
096(X'60' 
100(X'64' 
104(X'68' 
108(X'6C' 

112(X'70' 
116(X'74' 
120(X'78' 



Reason 
Code (RO) 

04(X'04') 

05(X'05') 

06(X'06') 

07(X'07') 



Meaning 

Invalid data set size specified for ALLOC =MOV. 

The data set is not a PDS for an ALLOC^MOV. 

The data set is not a PDS for an ALLOC=ABS. 

No directory quantity specified for a PDS for an 
ALLOC=ABS. 

Invalid JFCB or partial DSCB pointer. 

Requested directory space is larger than the space 
available on this volume. 

Nonindexed VTOC not supported for REALLOC 
ALLOC=ABS request. 

Invalid user label request. 

Invalid UCB pointer. 

DOS VTOC cannot be converted to an OS VTOC. 

No space parameter given for a new data set or 
zero space requested at absolute track zero. 

Invalid request for ISAM index. 

ISAM multivolume index not allowed. 

Invalid ISAM DSNAME element. 

ISAM multivolume overflow request not allowed. 

ABSTR and CYL requests conflict. 

CYL and CONTIG requests conflict. 

Invalid space subparameter. 

Primary space request for an ISAM data set is zero, 
or primary space for an ABSTR request is zero. 

Duplicate ISAM index request. 

User labels not supported. 

Invalid combination of values for DSSIZE and 
MINAU. 
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Return Reason 

Code (R15) Code (RO) 

124(X'7C') 

128(X'80') 

132(X'84') 
136(X'88') 
140(X'8C') 
144(X'90») 

148(X'94') 
152(X'98') 

156(X'9C') 

160(X'A0') 

164(X'A4') 

168(X'A8') 

172(X'AC') 
176(X'B0') 

180(X'B4') 

184(X'B8') 
188(X»BC') 



Meaning 

DSSIZE is not a multiple of MINAU. 

Directory space requested is larger than primary 
space. 

Space request must be ABSTR for DOS volume. 

Invalid F3DSCB pointer. 

ISAM index must be requested before prime area. 

Last concatenated DD card unnecessary or invalid 
for this ISAM data set. 

Overlapping extents in the VTOC. 

Overlapping DOS split cylinder extents in the 
VTOC. 

DADSM allocation terminated because of possible 
VTOC errors. 

ISAM allocation terminated because of possible 
VTOC errors. 

Allocation terminated because of DOS stacked 
pack format. 

RACF define failed, data set profile already 
defined. 

User not authorized to define data set. 

Installation exit rejected this request with a return 
code of 8. No further volumes should be 
attempted. 

Installation exit rejected this request with a return 
code of 4. For a nonspecific volume request, 
another volume may be attempted. 

RACF define with modeling specified and model 
not found. 

Invalid F2DSCB pointer. 
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Message Displays on the IBM 3480 Magnetic Tape Subsystem 



The MSGDISP macro displays a message on the ffiM 3480. With MSGDISP, you 
can specify the message to be displayed and how to display it (for example, steady 
or flashing). The six main parameters of the macro and their functions are: 

MOUNT Displays an "M" in position 1 of the display area during a mount 
request until a volume is loaded and made ready. The "M" is 
followed by the volume serial number and label type. 

VERIFY Shows that a volume has been accepted by displaying its serial 
number and label type in positions 2 through 8. 

RDY Displays text in positions 2 through 7 while a data set is open. 

DEMOUNT Displays a volume disposition indicator in position 1 until a volume is 
demounted. 

RESET Clears the display area. 

GEN Provides the full range of display options, including the option to 

alternate two messages. 

All except the RDY parameter require that you be in supervisor state, have a 
storage protect key of through 7, or be authorized by the authorized program 
facility. 

For MVS/XA, you may specify the lOSLEVEL (priority) of the request with the 
FORCE parameter. lOSLEVEL support replaces single-level I/O quiescing with 
multilevel quiescing; the higher the lOSLEVEL value, the greater your priority to 
control the device. 

The MSGDISP macro generates a parameter list as input to an SVC routine. 

MSGDISP may be coded in the standard, execute, and list forms. 

The formats for specifying MSGDISP with the six main parameters, and the return 
codes generated by MSGDISP, are given in the sections that follow. 

MSGDISP — ^Displaying a Mount Message 

The format for specifying MSGDISP with the MOUNT parameter is: 



[symbol] 


MSGDISP 


MOUNT 

,lJCB=(reg) 

[,FORCE={NO 1 YES | n \ keyword \ (reg)]] 

[,LABEL={'A' 1 'N' | •§• | 'X' | addr^] 

[,MF=|L 1 (E,addr)}] 

ISER={' volser'laddr^] 

[, lEST^INO 1 YES}J 

[,WAIT={NO|YES}l 
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MOUNT 

displays an "M" in position 1 of the display area during a mount request. 
The "M" is followed by a volume serial number and label type. The display 
flashes on and off until a volume is loaded and ready. If the device is ready 
at the time a mount request is issued, the "M" is not displayed. 

UCB=rregJ— (2-12) 

specifies a register containing the UCB address for the device. 

FORCE={NO I YES | n \ keyword | (reg)} 

specifies the priority (lOSLEVEL) for the display request's I/O. The higher 
the lOSLEVEL value, the greater the priority. 

If you do not specify the FORCE parameter, the default is FORCE=NO. 

NO 

prevents execution of a display request for a device whose I/O is 
being quiesced. The lOSLEVEL is set to the installation default, as 
indicated m the CVTIONLV field of the CVT. 



YES 



forces execution of a display request for a device even if its I/O is 
being quiesced. The lOSLEVEL is set to 9, the highest priority. 



specifies a decimal number from 1 to 9, to be used as the lOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 



keyword 

specifies a label equated to an lOSLEVEL value: 



NORMAL 


1 


QUIESCE 


2 


DAW 


3 


DDR 


4 


DYNPATH 


5 


UNCRSV 


6 


CHPRCVY 


7 


SCHRCVY 


8 


FDEV 


9 



ireg) 



specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the lOSLEVEL. 



LABEL={«A' I 'N' | 'Sj 'X' U^^r} 

displays the label type of the mounted volume in position 8. If you specify 
an unknown label type other than a blank, a '*?" is displayed. 



'A' 



specifies ISO/ANSI/FIPS (AL) or ISO/ANSI/FIPS with user labels 
(AUL). Specify in apostrophes. 
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specifies no labels (NL), LTM (DOS), or bypass label processing 
(BLP). Specify in apostrophes. 



specifies IBM Standard (SL) or IBM Standard with user labels (SUL). 
Specify in apostrophes. 



specifies nonstandard labels (NSL). Specify in apostrophes. 

addr — ^RX-type address, A-type address, or (2-12) 

specifies an in-storage address of an area containing an "A", "N", 
"S", or "X" (see the following explanations of these characters). For 
MF=L, you may only specify an A-type address. 

MF={L|(E,a^^r)} 

specifies either the execute or the list form of MSGDISP. If you do not 
specify this parameter, the standard form of the macro is used. 

L 

specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

{E,addr) 

specifies that the execute form of the macro and an existing parameter 
list are used. 

addr — RX-type address, ( 1 ) , or (2- 1 2) 

specifies an in-storage address of the parameter list. 

SER={'vo/ser'Ut/^/J 

specifies the serial number of the volume to be mounted. The serial number 
is displayed in positions 2 through 7. If you do not specify SER, the system 
supplies the volume serial number. If the serial number is not available, a 
scratch volume is used, unless the volume use attribute indicates a default of 
"PRIVAT". 

' volser^ 

specifies the volume serial number as a literal. Specify in apostrophes. 

addr — RX-type address, A-type address, or (2-12) 

specifies an in-storage address of the volume serial number. For 
MF=L, you may only specify an A-type address. 

TEST=|NO|YES} 

specifies whether to test the UCB to determine if the device is capable of 
displaying messages. 

NO 

specifies that the SVC routine will test the UCB. 



1 86 MVS/XA System-Data Administration 



YES 

specifies testing the UCB before the SVC call. 

Note: TEST=YES requires you to include the UCB mapping macro 
(lEFUCBOB) in the source code. 

WAIT=|NO|YESJ 

specifies when control is returned to you. 



NO 



YES 



specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 



specifies that control is to be returned after I/O is complete. 



MSGDISP — Displaying a Verify Message 

The format for specifying MSGDISP with the VERIFY parameter is: 



symbo1\ 


MSGDISP 


VERIFY 

,UCB=freg; 

l,FORCE={NO 1 YES | n \ keyword \ {reg)\\ 

l,LABEL={'A' 1 'N' | 'S' | 'X' \addiW 

l,MF={L|(E,fl^^r)}l 

l,SER={'vf>/5er'|ac?J/il 

l,lEST=|NO|YES}l 

l,WAIT={NO|YES}l 



VERIFY 

displays the serial number and label type of a volume that has been accepted 
in positions 2 through 8. Position 1 remains blank. The display lasts until 
the next display request is executed. 

UCB=rreg^-(2-12) 

specifies a register containing the UCB address for the device. 

FORCE=(NO I YES | n \ keyword \ {reg)\ 

specifies the priority (lOSLEVEL) for the display request's I/O. The higher 
the lOSLEVEL value, the greater the priority. 

If you do not specify the FORCE parameter, the default is FORCE=NO. 



NO 



YES 



prevents execution of a display request for a device whose I/O is 
being quiesced. The lOSLEVEL is set to the installation default, as 
indicated in the CVTIONLV field of the CVT. 



forces execution of a display request for a device even if its I/O is 
being quiesced. The lOSLEVEL is set to 9, the highest priority. 
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n 

specifies a decimal number from 1 to 9, to be used as the lOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 

keyword 

specifies a label equated to an lOSLEVEL value: 



NORMAL 


1 


QUIESCE 


2 


DAW 


3 


DDR 


4 


DYNPATH 


5 


UNCRSV 


6 


CHPRCVY 


7 


SCHRCVY 


8 


FUEV 


9 



ireg) 

specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the lOSLEVEL. 

LABEL^I'A' I 'N' | 'S' | '\addri 

specifies label tjrpe of the mounted volume in position 8 of the display. If an 
unknown label type other than a blank is specified, a "?" is displayed. 



specifies ISO/ANSI/FIPS (AL) or ISO/ANSI/FIPS with user (AUL) 
labels. Specify in apostrophes. 



•N' 



specifies no labels (NL), LTM (DOS), or bypass label processing 
(BLP). Specify in apostrophes. 



specifies IBM Standard (SL) or IBM Standard with user (SUL) labels. 
Specify in apostrophes. 



specifies nonstandard (NSL) labels. Specify in apostrophes. 

addr — ^RX-type address, A-tjrpe address, or (2-12) 

specifies an in-storage address of an area containing an "A", "N", 
"S", or "X" (see explanations below for these characters). For 
MF=L, you may only specify an A-type address. 

MF=|L|(E,atWr)J 

specifies either the execute or list form of MSGDISP. If you do not specify 
this parameter, the standard form of the macro is used. 

L 

specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 
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(E^addr) 

specifies that the execute form of the macro and an existing parameter 
list is to be used. 

addr — RX-type address, (1), or (2-12) 

specifies an in-storage address of the parameter list. 

SER=Vvolser'\addr] 

specifies the serial number of the volume that has been verified. The serial 
number displays in positions 2 through 7. If you do not specify SER, the 
system supplies the volume serial number. If the serial number is not 
available, a scratch volume is used, unless the volume use attribute indicates 
a default of "PRIVAT". 

' volser^ 

specifies the volume serial number as a literal. Specify in apostrophes. 

addr — ^RX-type address, A-type address, or (2-12) 

specifies an in-storage address of the volume serial number. For 
MF=L, you may only specify an A-type address. 

TEST=|NO|YES} 

specifies whether to test the UCB to determine if the device is capable of 
displaying messages. 

NO 

specifies that the SVC routine will test the UCB. 

YES 

specifies testing the UCB before the SVC call. 

Note: TEST=YES requires you to include the UCB mapping macro 
(lEFUCBOB) in the source code. 

WAIT:=|NO|YES} 

specifies when control is to be returned to you. 

NO 

specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 

YES 

specifies that control is to be returned after I/O is complete. 

M SGDISP — ^Displaying a Ready Message 

The format for specifying MSGDISP with the RDY parameter is: 



[symbol] 


MSGDISP 


RDY 

J)CB=addr 
l,MF=|L|(E,a^r)n 
ITXT=-Vmsgtxt'\addr ] 
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RDY 

displays the text supplied in the TXT parameter in positions 2 through 7 
while the data set is open. The display is steady (not flashing) and is 
enclosed in parentheses. The display is also written to the tape pool console 
(routing code 3, descriptor code 7). 

DCB=addr 

specifies the address of a DCB opened to a data set on the mounted volume. 
If multiple devices are allocated, the message display is directed to the one 
containing the volume currently in use. 

Note: If multiple devices or multiple volumes are allocated, you may update 
a message display after an end-of -volume condition by using the EOV exit 
specified in a DCB exit list. In the case of a concatenated data set with 
unlike characteristics, the DCB OPEN exit may be used to update the 
display. 

addr — RX-type address, A-type address, or (2-12) 

specifies an in-storage address of the opened DCB. For MF=L, you 
may only specify an A-type address. 

MF=|L I (E,addr)} 

specifies either the execute or list form of MSGDISP. If this parameter is not 
specified, the standard form of the macro is used. 



specifies the list form of MSGDISP. This generates a parameter Hst 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

(E^addr) 

specifies that the execute form of the macro and an existing parameter 
list is to be used. 

addr — RX-type address, (1), or (2-12) 

specifies an in-storage address of the parameter list. 

TXT=Vmsgtxt' I addri 

specifies up to six characters to display in positions 2 through 7 of the 
display. If you do not specify TXT, blanks are displayed. 

^ntsgtxt* 

specifies the text as a literal. Specify in apostrophes. 

addr — RX-type address, A-type address, or (2-12) 

specifies an in-storage address of an area containing the text to be 
displayed. For MF=L, you may only specify an A-type address. 
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MSGDISP — Displaying a Demount Message 

The fonnat for specifying MSGDISP with the DEMOU>rr parameter is: 



[symboll 


MSGDISP 


DEMOUNT 

^JCB=^(reg) 

[,DISP={'D' 1 'K' 1 'R' k^^'il 
[,FORCE={NO 1 YES | n \ keyword \ (reg)}] 
[,MF={L|(E,a^r)n 

[,MLABEL=|'A' | 'N' | 'S' | 'X' \nfidr]] 
[MSER=Vvolser-to-mount^ \addr}] 
ISERM' volser*\addr}] 
[,TEST={NO|YES}] 
[,WAIT={NO|YES}] 



DEMOUNT 

Displays a volume disposition indicator in position 1 until the volume is 
demounted. Optionally, you may display the serial number of the volume to 
be demounted at the same time. The display flashes on and off. If a volume 
is not mounted on the device when the display request is executed, blanks 
are displayed. 

The demount message may be displayed alternately (flashing) with a mount 
message for the next volume by specifying the MSER parameter. 

VCB=(reg)—(2-12) 

specifies a register containing the UCB address for the device. 

DISP=|'D'|'K'|'R'|a^'i 

specifies the character to display in position 1, representing the volume 
disposition. 



•D' 



Demount a public volume. Specify in apostrophes. 

Note: "D" also displays when you specify an invalid character or 
when the volume use attribute is unknown (as in an automatic volume 
recognition (AVR) error when reading a label). 



Keep a private volume and return it to the library. Specify in 
apostrophes. 



Retain a private volume near the device for further use. Specify in 
apostrophes. 

addr — ^RX-type address, A-type address, or (2-12) 

specifies an in-storage address of an area containing a "D", "K", or 
"R". For MF=L, you may only specify an A-type address. 

FORCE=|NO I YES | n | keyword \ (reg)] 

specifies the priority (lOSLEVEL) for the display request's I/O. The higher 
the lOSLEVEL value, the greater the priority. 
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If you do not specify the FORGE parameter, the default is FORCE=NO. 

NO 

prevents execution of a display request for a device whose I/O is 
being quiesced. The lOSLEVEL is set to the installation default, as 
indicated in the CVTIONLV field of the CVT. 



YES 



forces execution of a display request for a device even if its I/O is 
being quiesced. The lOSLEVEL is set to 9, the highest priority. 



specifies a decimal number from 1 to 9, to be used as the lOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 



keyword 

specifies a label equated to an lOSLEVEL value: 



NORMAL 


1 


QUIESCE 


2 


DAW 


3 


DDR 


4 


DYNPATH 


5 


UNCRSV 


6 


CHPRCVY 


7 


SCHRCVY 


8 


FDEV 


9 



ireg) 



specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicatmg the lOSLEVEL. 



MF={L|(E,a^^r)} 

specifies either the execute or list form of MSGDISP. If you do not specify 
this parameter, the standard form of the macro is used. 



specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

{E,addr) 

specifies that the execute form of the macro and an existing parameter 
list is to be used. 

addr — ^RX-type address, (1), or (2-12) 

specifies an in-storage address of the parameter list. 

MLABEL={'A' | 'N* | 'S' | 'X'\addA 

displays the label t3rpe of the volume to be loaded and made ready following 
a demount, in position 8. If you specify an unknown label type other than a 
blank, a "?" is displayed. You may only specify this parameter if you also 
specify the MSER parameter. 
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specifies ISO/ANSI/FIPS (AL) or ISO/ANSI/FIPS with user (AUL) 
labels. Specify in apostrophes. 

•N' 

specifies no labels (NL), LTM (DOS), or bypass label processing 
(BLP). Specify in apostrophes. 



specifies IBM Standard (SL) or IBM Standard with user (SUL) labels. 
Specify in apostrophes. 



specifies nonstandard (NSL) labels. Specify in apostrophes. 

addr — RX-type address, A-type address, or (2-12) 

specifies an in-storage address of an area containing an "A", "N", 
"S", or "X" (see the following explanations of these characters). For 
MF=L, you may only specify an A-type address. 

MSER=V volser-to-mount*\ciddri 

displays the mount message for the next volume alternately (flashing) with 
the demount message. The display continues untUyou demount the current 
volume. At that time, the mount message will display (flashing) until you 
load the volume and make the device ready. If no volume is mounted at the 
time the demount and mount messages are executed, only the mount 
message will display (flashing) until the volume is loaded and ready. 

' volser-to-mount^ 

specifies the volume serial number of the volume to be mounted, as a 
literal. Specify in apostrophes. 

addr — ^RX-type address, A-type address, or (2-12) 

specifies an in-storage address of the volume serial number of the 
volume to be mounted. For MF=L, you may only specify an A-type 
address. 

SER=rvo&er' M^/i 

specifies the serial number of the volume to be demounted. The serial 
number is displayed in positions 2 through 7. If you do not specify SER, the 
system supplies the volume serial number. If the serial number is not 
available, a scratch volume is used, unless the volume use attribute indicates 
a default of "PRIVAT". 

^volser^ 

specifies the volume serial number as a literal. Specify in apostrophes. 

addr — ^RX-type address, A-type address, or (2-12) 

specifies an in-storage address of the volume serial number. This 
parameter is not valid for the MF=L form. For MFs=L, you may only 
specify an A-type address. 

TEST={NO|YES} 

specifies whether to test the UCB to determine if the device is capable of 
displaying messages, message display SVC routine. 
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NQ 



YES 



specifies that the SVC routine will test the UCB. 



specifies testing the UCB before the SVC call. 

Note: TEST=YES requires you to include the UCB mapping macro 
(lEFUCBOB) in the source code. 

WAIT={NO|YES} 

specifies when control is to be returned to you. 



NO 



YES 



specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 



specifies that control is to be returned after I/O is complete. 



MSGDISP — Resetting the Message Display 

The format for specifying MSGDISP with the RESET parameter is: 



\symbol\ 


MSGDISP 


RESET 

,{\}C^=(reg) 1 ,UCBL=a^<//i 
[,FORCE=|NO 1 YES | n \ keyword | (,reg)\\ 
l,MF=|L|(E,ati/r)}l 
I, lEST={NO 1 YESn 
l,WAIT=|NO|YES}l 



RESET 

clears all existing data on the display. If you specify WArr=NO and the last 
service requested was a demount, the display is not cleared. 

After being cleared, the display will show the device's internal status message 
(for example, a message indicating that the device is ready). 

UCB=rreg;— (2-12) 

specifies a register containing the UCB address for the device. 

UCBL=fl^^r — RX-type address, A-type address, (0), or (2-12) 

specifies the address of a list containing a maximum of 64 words. Each word 
in the list contains the address of a UCB representing a device whose display 
is to be reset. The end of the list is indicated by a ' 1 ' in the high order bit of 
the last address in the list. If an error is encountered while processing the 
list, register 1 points to the associated UCB when you regain control. 

You cannot specify UCBL with TEST=YES and WAIT=NO. 

FORCE=eiO I YES I n I keyword \ {reg)\ 

specifies the priority (lOSLEVEL) for the display request's I/O. The higher 
the lOSLEVEL value, the greater the priority. 
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If you do not specify the FORCE parameter, the default is FORCE=NO. 

NO 

prevents execution of a display request for a device whose I/O is 
being quiesced. The lOSLEVEL is set to the installation default, as 
indicated in the CVTIONLV field of the CVT. 



YES 



forces execution of a display request for a device even if its I/O is 
being quiesced. The lOSLEVEL is set to 9, the highest priority. 



specifies a decimal number from 1 to 9, to be used as the lOSLEVEL 
value. A high number indicates a higher priority request for the 
device. 



keyword 

specifies a label equated to an lOSLEVEL value: 



NORMAL 


1 


QUIESCE 


2 


DAW 


3 


DDR 


4 


DYNPATH 


5 


UNCRSV 


6 


CHPRCVY 


7 


SCHRCVY 


8 


FDEV 


9 



ireg) 



specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the lOSLEVEL. 



MF={L I {E,addr)\ 

specifies either the execute or the list form of MSGDISP. If you do not 
specify this parameter, the standard form of the macro is used. 

L 

specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

{E,addr) 

specifies that the execute form of the macro and an existing parameter 
list is to be used. 

addr — RX-type address, (1), or (2-12) 

specifies the address of the parameter list. 

TEST={NQ|YES} 

specifies whether to test the UCB to determine if the device is capable of 
displaying messages. 
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NO 

specifies that the SVC routine will test the UCB. 

YES 

specifies testing the UCB before the SVC call. You cannot specify 
TEST=YES if you also specify the UCBL parameter. 

Note: TEST=YES requires you to include the UCB mapping macro 
(lEFUCBOB) in the source code. 

WAIT=|NO I YES} 

specifies when control is to be returned to you. 

NO 

specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 

You cannot specify WAIT=NO if you also specify the UCBL 
parameter. 

YES 

specifies that control is to be returned after I/O is complete. 

Note: Demount messages can be reset only if WArr=YES is 
specified. 
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MSGDISP—- Providing the Full Range of Display Options 

The format for specifying MSGDISP with the GEN parameter is: 



[symboll 


MSGDISP 


GEN 

[,FLASH={STEADY | STEADY2 

1 BLINK 1 BLINK2 | ALT}] 

[,FORCE=|NO 1 YES | n \ keyword \ (reg)}] 

UMF={L\iE,addrm 

[,IEST=(NO|YESn 

ITXT=V msgtxt'\addr}] 

UTXT2=Valtmsgtxr \addr^] 

r.VOL= {STATIC 1 REMOVE | INSERT | SWAPJ] 

[,WAIT={NO|YES}l 



GEN 



specifies the full range of display options. 



VCB=(reg)—(2-12) 

specifies a register containing the UCB address for the device. 

FLASH= {STEADY | STEADY! | BLINK | BLINK2 | ALT] 

specifies message display mode. 

Note: If you specify VOL=SWAP, messages will always be displayed as if 
you had specified FLASH = ALT 

STEADY 

specifies that the primary message (TXT) is to be displayed without 
flashing. 

STEADY! 

specifies that the alternate message (TXT2) is to be displayed without 
flashing. 

BLINK 

specifies that the primary message (TXT) flash on and off at a rate of 
approximately two seconds on and one-half second off. 

BLINK! 

specifies that the alternate message (TXT2) flash on and off at a rate 
of approximately two seconds on and one-half second off. 

ALT 

specifies that the primary and alternate messages (TXT and TXT2) 
flash on and off alternately, at a rate of approximately two seconds on 
and one-half second off. 

FORCE={NO I YES | n | keyword | (reg)} 

specifies the priority (lOSLEVEL) for the display request's I/O. The higher 
the lOSLEVEL value, the greater the priority. 

If you do not specify the FORCE parameter, the default is FORCE=NO. 
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NO 

prevents execution of a display request for a device whose I/O is 
being quiesced. The lOSLEVEL is set to the installation default, as 
indicated in the CVTIONLV field of the CVT. 

YES 

forces execution of a display request for a device even if its I/O is 
being quiesced. The lOSLEVEL is set to 9, the highest priority. 



specifies a decimal number from 1 to 9, to be used as the lOSLEVEL 
value. A high niunber indicates a higher priority request for the 
device. 

keyword 

specifies a label equated to an lOSLEVEL value: 

NORMAL 1 
QUIESCE 2 
DAW 3 
DDR 4 

DYNPATH5 
UNCRSV 6 
CHPRCVY 7 
SCHRCVY 8 
FDEV 9 



{reg) 



specifies that the low-order byte of the indicated register (2 through 
12) contains a value between 1 and 9, indicating the lOSLEVEL. 



MF«|L|(E,fl^r)} 

specifies either the execute or the list form of MSGDISP. If you do not 
specify this parameter, the standard form of the macro is used. 



specifies the list form of MSGDISP. This generates a parameter list 
that can be used as input to the execute form. The execute form can 
modify the parameter list. 

{%addr) 

specifies that the execute form of the macro and an existing parameter 
list is to be used. 

addr 

specifies an in-storage address of the parameter list. Specify 
either an RX-type address or a register m the range of 2 
through 12. 

TEST=|NO|YESJ 

specifies whether to test the UCB to determine if the device is capable of 
displaying messages. 
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NO 

specifies that the SVC routine will test the UCB. 

YES 

specifies testing the UCB before the SVC call. 

Note: TESTs=YES requires you to include the UCB mapping macro 
(lEFUCBOB) in the source code. 

TXT={'m5g/xr' \addj\ 

specifies 8 characters to be shown in positions 1 through 8 of the display. If 
you do not specify TXT, blanks are displayed. 

^msgtxV 

specifies the 8 characters as literals. Specify in apostrophes. 

addr — ^RX-type address, A-type address, or (2-12) 

specifies an in-storage address of an area containing the 8 characters. 
For MF=L, you may only specify an A-type address. 

TXT2 = { • altmsgtxt' \ addr^ 

specifies 8 alternate characters to display in positions 1 through 8 of the 
display. If you do not specify TXT2, blanks are displayed. 

^altmsgtxV 

specifies the 8 characters as literals. Specify in apostrophes. 

addr — ^RX-t5T)e address, A-type address, or (2-12) 

specifies an in-storage address of an area containing the 8 characters. 
For MF=L, you may only specify an A-type address. 

VOL= ISTATIC I REMOVE i INSERT | SWAPJ 

specifies message display mode, based on volume status. 

STATIC 

specifies that messages will display without regard to volume status 
until the next message request is executed, or until the next command 
initiates volume movement. 

REMOVE 

specifies that messages will display until the current volume is 
demounted. This parameter is ignored if a volume is not mounted 
when the request is executed. 

INSERT 

specifies that messages will display untU a volume is present, the tape 
threaded, and the active/inactive switch is in the active position. This 
parameter is ignored if a volume is loaded and ready when the request 
is executed. 

SWAP 

specifies that messages will always display as if FLASH=ALT were 
specified. The data from TXT and TXT2 displays alternately 
(flashing) until the current volume has been demounted. Then only 
TXT2 will display (flashing) until a new volume is loaded and ready. 
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If no volume is mounted when this parameter is specified, only TXT2 
data will display (flashing) until a new volume is loaded and ready. 

WAIT=|NO I YES^ 

specifies when control is to be returned to you. 



NO 



YES 



specifies that control is to be returned before I/O is complete. I/O 
return codes are not returned, and I/O errors are recorded in the same 
manner as any permanent error by the error recovery procedure. 



specifies that control is to be returned after I/O is complete. 



Return Codes from MSGDISP 



When the system returns control to the problem program, the low-order byte of 
register 15 contains a return code. The low-order byte of register may contain a 
reason code as follows: 

Return Reason 

Code (R 15) Code(RO) Meaning 



OO(X'OO') 
04(X'04') 
08(X'08') 

08(X'08') 



Successful completion. 

Device does not support MSGDISP. 

Unauthorized request (failed TESTAUTH for 
proper authority level) or invalid input parameters 
(including DCB or UCB). 

1 (X ' 1 ' ) Invalid parameter. 

02(X'02') InvaUd DCB or DEBCHK error. 

03 (X ' 03 ' ) Environmental error. 

04(X'04') Authorization violation. 

05(X'05') InvaUd UCB. 

06(X'06') Invalid request. 

1 1(X ' OB • ) Unsuccessful ESTAE macro call. 

12(X»0C') Unsuccessful GETMAIN request. 
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Return Reason 

Code (R15) Code (RO) Meaning 



1 2(X' OC ) I/O error (I/O Supervisor posted the request for 

an error). 



Note: An I/O error occurs for load display if the 
drive display has a hardware failure. 



If you get return code X'04' or X'OC on a RESET UCBL operation, register 1 
points to the UCB associated with the error when you regain control. 
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Chapter 7. Maintaining SYS1.IMAGELIB 



This chapter describes how to maintain the system image library 
(SYSl.IMAGELIB) and UCS images for the IBM 1403, 3203, and 3211 Printers, 
and FCB images for the IBM 3203, 3211, and 4245 Printers. Sample JCL 
jobstreams for adding a UCS image to SYSl.IMAGELIB for the IBM 1403, 3203, 
and 321 1 Printers are shown in Figure 37 on page 206, Figure 38 on page 207, 
and Figure 39 on page 208, respectively. 

SYSl.IMAGELIB does not contain UCS images for the IBM 3262 Model 5, 4245, 
or 4248 Printers, but instead contains image tables. By means of these image 
tables, the system relates the user-requested UCS image to the corresponding print 
band. Figure 40 on page 210 defines and describes the structure of an image 
table entry. The contents of IBM-supplied image tables for the IBM 4245 and 
4248 Printers are shown in Figure 41 on page 211 and Figure 42 on page 212, 
respectively. The IBM 3262 Model 5 Printer uses the same image table as the 
4248. 

This chapter also describes How to maintain the UCS image table in 
SYSl.IMAGELIB for the IBM 3262 Model 5, 4245, and 4248 Printers. To 
determine which print bands are available, see: 

• IBM 3262 Printer Model 5 Product Description, containing information on 
band IDs for the 3262 Model 5 Printer 

• IBM 4245 Printer Model 1 Component Description and Operator's Guide, 
containing information on band IDs for the 4245 Printer 

• IBM 4248 Printer Description, containing information on band IDs for the 
4248 Printer 

SYSl.IMAGELIB also contains control modules for the IBM 3800 Printing 
Subsystem. You can use the lEBIMAGE utility program to create and maintain 
these control modules (character arrangement table modules, graphic character 
modification modules, copy modification modules, library character set modules, 
and FCB modules). 

You can also use lEBIMAGE to create and maintain FCB modules in 
SYSl.IMAGELIB for the 4248 Printer. You can use FCB modules created for the 
4248 with the 3262 Model 5 Printer. However, the 3262 Model 5 does not 
support variable printer speeds or the horizontal copy feature of the 4248. For 
more information about lEBIMAGE, see Utilities. 

This chapter also describes how to retrieve an FCB image from SYSl.IMAGELIB 
for modification. 
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To use the information presented in tliis chapter, you should be familiar with the 
subjects of the following publications: 

• Data Administration: Macro Instruction Reference describes the SETPRT macro 
that you can use to specify the images or modules that you want. 

• JCL Reference describes the CHARS, MODIFY, UCB, and FCB parameters 
of the DD statement that are processed at OPEN time. 

• IBM 2821 Control Unit Component Description contains information on 
creating a user-designed chain/ train for the 1403 Printer. 

• IBM 3203 Printer Component Description and Operator's Guide contains 
information on creating a user-designed train for the 3203 Printer. 

• IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 Printer 
Control Unit Component Description and Operator's Guide contains information 
on creating a user-designed train for the 32 11 Printer. 

• JES2 Initialization and Tuning and Network Job Entry Facility for JES2 contain 
reference information for JES2. 

• JES3 Initialization and Tuning 

You can use the SPZAP service aid to display and modify an existing member of 
SYSl.IMAGELIB. Service Aids describes the use of SPZAP. 



UCS Images in SYSl.IMAGELIB 



Most IBM standard character set images are included in SYSl.IMAGELIB at 
system generation time, through the DATAMGT macro and an lODEVICE macro 
for the specified printer. (For details on the DATAMGT and lODEVICE macros, 
see System Generation.) The standard character set images for the 1403, 3203, and 
3211 Printers are shown below. 



Printer 


Images 


1403 or 3203 


AN, HN, PCAN, PCHN, PN, QNC, QN, RN, SN, TN, 

XN,YN 


3211 


A11,G11,H11,P11,T11 



Adding a UCS Image to the Image Library 



Using the assembler and linkage editor, you may add a UCS image to those that 
reside in SYSl.IMAGELIB. No executable code is generated; the assembler 
prepares DCs, and the linkage editor puts them into SYSl.IMAGELIB. The new 
UCS image must be structured according to the following rules: 

1. The member name must be 5 to 8 characters long; the first 4 characters must 
be the appropriate UCS prefix, as shown below. 
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UCSl - 1403 Printer 

UCS2 - 3211 Printer (or 3211 -compatible printer) 

UCS3 - 3203 Printer 

These first four characters must be followed by a character set code, one to 
four characters long. Any valid combination of letters and numbers under 
assembler language rules is acceptable. However, the single letters U or C 
must not be used, because they are sjmibols for special conditions recognized 
by the system. The assigned character set code must be specified on the DD 
statement or SETPRT macro to load the image into the UCS buffer. 

You can supply an alias name for a new image with the ALIAS statement of 
the linkage editor. (For more information on the ALIAS statement, see 
Linkage Editor and Loader User's Guide.) 

The first byte of the character set image load module specifies whether the 
image is a default. (Default images may be used by the system for jobs that do 
not request a specific image.) Specify the following in the first bjrte: 

For JES2: 

X'80' indicates a default image. 

X'40' indicates that the output is to be folded. 

X'CO' indicates default image and folding. 

X'OO' indicates that the image is not to be used as a default. 
For non-JES2: 

X'80' indicates a default image. 

X'OO' indicates that the image is not to be used as a default. 

The second byte of the load module indicates the number of Unes (n) to be 
printed for unage verification. See "Verifying the UCS Image" on page 215 
for more information on image verification. 

Each byte of the next n bytes indicates the number of characters to be printed 
on each verification line. For the 321 1 Printer, the maximum number of 
characters printed per line is 48; the bytes of associative bits (see note 5) are 
not printed during verification. 

The UCS image itself must follow the previously described fields. The image 
must fill the number of bytes required by the printer; see the table below for 
image lengths. Note that, because of Assembler language syntax, two 
apostrophes or two ampersands must be coded to represent a single apostrophe 
or a single ampersand, respectively, within a character set image. 
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UCS Coding Examples 



Printer 


Image Lengtli 


1403 


240 bytes 


3203 


304 bytes (240 characters followed by 64 bytes of 
associative bits) 


3211 


512 bytes (432 characters followed by 15 bytes of X»(X)' 
64 bytes of associative bits, and one reserved byte of 
X'OO') 



Associative bits must be coded to prevent data checks when adding a UCS 
image to SYSl.IMAGELIB. See the appropriate printer manual for more 
information on coding associative bits. 



Figure 37 contains an example of adding a 1403 UCS image, YN, to 

SYS 1.IMAGELIB or the image library. Notes follow Figure 39 on page 208. 

Figure 38 on page 207 shows the code used to add a 3203 UCS image, YN, 
to SYS1.IMAGELIB or the image library. 

Figure 39 on page 208 shows the code used to add a 321 1 UCS image, Al 1, 
to SYSl.IMAGELIB or the image library. 



//ADDYN JOB MSGLEVEL=1 

//STEP EXEC PROC=ASMFCL , FARM . ASM= ' NODECK , LOAD ' , 

// FARM. LKED=' LIST, OL,REFR, RENT, XREF' 

//ASM. SYS IN DD * 

UCS1YN CSECT 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 



X'80' 
AL1 (6) 
AL1 (39) 
AL1 (42) 
AL1 (39) 
AL1 (39) 
AL1(42) 
AL1 (39) 



(THIS IS A DEFAULT IMAGE) 

(NUMBER OF LINES TO BE PRINTED) 

(39 CHARACTERS TO BE PRINTED ON LINE 

TO BE 

TO BE 

TO BE 

TO BE 



(42 
(39 
(39 
(42 
(39 



CHARACTERS 
CHARACTERS 
CHARACTERS 
CHARACTERS 
CHARACTERS 



PRINTED ON LINE 
PRINTED ON LINE 
PRINTED ON LINE 
PRINTED ON LINE 



TO BE PRINTED ON LINE 



1) 
2) 
3) 
4) 
5) 
6) 



THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE 



DC 
DC 
DC 
DC 
DC 
DC 
END 



C 1 234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , 
C • 1 234567890STABCDEFGHIJKLMNOFQRSTUVWXYZ* , 
C • 1 234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , 
C • 1 234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , 
C ' 1 234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , 
C ' 1 234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , 



#-$' 



#-$• 



/♦ 

//LKED . SYSLMOD DD DSNAME=SYS1 . IMAGELIB (UCS1 YN) ,DISP=OLD, 

// SPACE= (OVERRIDE SECONDARY ALLOCATION) 

Figure 37. Sample Code to Add a 1403 UCS Image to SYSl.IMAGELIB 
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Notes to Figure 37 on page 206, Figure 38 on page 207, and Figure 39: 

1 . The RENT and REFR linkage editor attributes are required. 

2. For the 3203 and 321 1 Printers, the 64 bytes of associative bits must be coded 
to avoid data checks. To determine how to code these bits for a particular 
image, see IBM 3203 Printer Component Description and Operator's Guide or 
IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 Printer 
Control Unit Component Description and Operator's Guide. 

3. Executing the ASMFCL procedure does not actually generate executable code. 
The assembler/linkage editor merely places the UCS image into 
SYS1.IMAGELIB. 

4. The SPACE parameter is overridden here because the ASMFCL cataloged 
procedure has secondary allocation specified. By eliminating the override you 
can use the original secondary allocation amount. 



UCS Image Tables in SYSl.IMAGELIB 



SYSl.IMAGELIB does not contam UCS images for the fflM 3262 Model 5, 4245, 
or 4248 Printers, but contains image tables. The UCS image for each band is 
stored, instead, in the printer, and is automatically loaded into the UCS buffer 
when the machine is powered on or a new band is installed. See Figure 40 on 
page 210 for the format of image table entries, and "Adding or Modifying a UCS 
Image Table Entry" on page 213 for information on how to add or modify an 
image table entry. 

SYSl.IMAGELIB contains one UCS image table for each type of printer that 
supports image tables. An image table contains an entry for most 
installation-standard IBM-supplied bands. The 4245 image table is named UCS5. 
The shared 4248 and 3262 Model 5 image table is named UCS6. 



Alias Names in Image Tables 



The image tables also define alias names for most installation-standard print bands 
used on the IBM 4245 and 4248 Printers. The IBM-supplied image tables do not 
provide ahas names for the IBM 3262 Model 5 Printer. 

Some print chains/trams/bands, such as SN and KA22, do not have alias names 
because there is no equivalent chain/train/band on other printers. You can assign 
an alias for these chains/trains with the linkage editor ALIAS statement. (For 
more information on the ALIAS statement, see Linkage Editor and Loader User's 
Guide.) For the 3262 Model 5, 4245, or 4248 Printer, you can add an alias name 
by adding or modifying an entry in the UCS image table. See "Adding or 
Modifying a UCS Image Table Entry" on page 213. A typical UCS image table 
entry is shown in Figure 40 on page 210. 
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//ADDA1 1 JOB MSGLEVEL=1 

//STEP EXEC PROC=ASMFCL, FARM. ASM='NODECK, LOAD' 

// FARM . LKED= ' LIST , OL , REFR , RENT , XREF ' 

//ASM. SYS IN DD * 

UCS2A1 1 CSECT 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 



X'80' 
AL1 (9) 
AL1 (48) 
AL1 (48) 
AL1 (48) 
AL1 (48) 
ALT (48) 
AL1 (48) 
AL1 (48) 
AL1 (48) 
AL1 (48) 



(48 

(48 

(48 

(48 

(48 

(48 

(48 

(48 

THE FOLLOWING NINE LINES REPRESENT 
NOTE 2 AMPERSANDS MUST BE CODED TO 



(THIS IS A DEFAULT IMAGE) 
(NUMBER OF LINES TO BE PRINTED) 
(48 CHARACTERS TO BE PRINTED ON 

TO 

TO 

TO 

TO 

TO 

TO 

TO 

TO 



CHARACTERS 
CHARACTERS 
CHARACTERS 
CHARACTERS 
CHARACTERS 
CHARACTERS 
CHARACTERS 
CHARACTERS 



THE 
GET 



PRINTED 
PRINTED 
PRINTED 
PRINTED 
PRINTED 
PRINTED 
PRINTED 
PRINTED 
TRAIN IMAGE 
1 IN ASSEMBLER 



BE 
BE 
BE 
BE 
BE 
BE 
BE 
BE 



ON 
ON 
ON 
ON 
ON 
ON 
ON 
ON 



LINE 
LINE 
LINE 
LINE 
LINE 
LINE 
LINE 
LINE 
LINE 



1) 
2) 
3) 
4) 
5) 
6) 
7) 
8) 
9) 



SYNTAX 



DC C 1<.+IHGFEDCBA*$-RQP0NMLKJX, 8SZYXWVUTS/a#098765432 ' 
DC C'1<.+IHGFEDCBA*$-RQPONMLKJSl,66ZYXWVUTS/a#098765432' 
DC C 1<.+IHGFEDCBA*$-RQP0NMLKJS{, 6SZYXWVUTS/a#098765432 ' 
DC C 1<.+IHGFEDCBA*$-RQP0NMLKJS{, &gZYXWVUTS/a#098765432' 
DC C 1<.+IHGFEDCBA*$-RQPONMLKJ58, ggZYXWVUTS/a#098765432' 
DC C 1<.+IHGFEDCBA*$-RQP0NMLKJSJ, &gZYXWVUTS/a#098765432 ' 
DC C 1<.+IHGFEDCBA*$-RQP0NMLKJX, ggZYXWVUTS/a#098765432' 
DC C 1<.+IHGFEDCBA*$-RQP0NMLKJJ8, ggZYXWVUTS/a#098765432' 
DC C 1<.+IHGFEDCBA*$-RQP0NMLKJ5I, ggZYXWVUTS/a#098765432' 
DC ISX'OO' (RESERVED FIELD, BYTES 433-447) 

THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS, 

UCSB BYTE POSITIONS 448-511 



DC 
DC 
DC 
DC 
DC 
END 



X'COI 01 01 01 0101 01 01 01 00040404240004010' 
X' 101 0101 01 0101 01 000404041000040401 010' 
X' 101010101010004040000000101010101010' 
X' 10101010004040444800' 
X'OO' (RESERVED FIELD, BYTE 512) 



/* 

//LKED . SYSLMOD DD DSNAME=SYS1 

// SPACE= 



IMAGELIB(UCS2A1 1 ) ,DISP=OLD, 
(OVERRIDE SECONDARY ALLOCATION) 



Figure 39. Sample Code to Add a 321 1 UCS Image to SYSl.IMAGELIB 
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yourself. "Adding or Modifying a UCS Image Table Entry" on page 213 
describes how to add entries to the UCS image table. For a list of the bands 
available for the 3262 Model 5, see IBM 3262 Printer Model 5 Product Description. 



Adding or Modifying a UCS Image Table Entry 



If you plan to use a new UCS image name/aUas with the 3262 Model 5, 4245, or 
4248 Printer, you must add an entry for that image name/alias to the appropriate 
UCS image table. As shown below, use the assembler to compile the image table 
module, then link-edit the object file into SYSl.IMAGELIB. Similarly, if you want 
to select a new default image or change the description on an old image, you must 
change the image table. 

To build new UCS table entries, or to change the format of old entries, use the 
following procedure. Also, see "Example 1: Adding a New Band ID to the 4245 
UCS Image Table (UCS5)" on page 216 and "Example 2: Adding a New Default 
Entry to the 4248 UCS Image Table (UCS6)." on page 216. 

1. Issue the IGGUCSIT macro, as described below, to build a new UCS image 
table entry. If you are updating the image table as shown in the following two 
examples, the linkage editor builds a new entry at the start of the table, even if 
you intended to replace an existing entry. When the system subsequently uses 
the table, it encounters the new entry first, thus the old one is effectively 
replaced. 

2. Include the UCS image table source, using the IGGUCS5 or IGGUCS6 macro, 
both of which are found in SYSl.MACLIB. 

3. Assemble the image table module (UCS5 or UCS6). 

4. Link-edit the assembled module into SYS 1 .IMAGELIB. 
Note: RENT and REFR are required attributes. 

The IGGUCSIT macro instruction has the following format: 



iGGucsrr 


MF={LIST|DSECT} 




,NAME= image name 




[,ALIAS=//wflge alias] 




l,DEFAULT={YES 1 NO^ 




lDESCR=description] 




(,DEVICE=|4245 | 4248}] 




I,VLENGTH=(/ii,n2,. . .n)] 




[,FOLD=[YES|NO}l 



MF=aiSI|DSECT} 

specifies the form of the macro instruction. 
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Byte 1 



9 10 11 12 



16 17 



Hh 



Hh 



32 



•ih 



l 



■<l- 



Description data ' 
^ Length of description data^ 



"^ Lengths of verification lines^ 
(V LENGTH); one byte per line 



-^ Number of verification lines^ 
-^ Reserved (set to zero) 



■^ Description offset (set to zero if omitted) 

"7 Verification offset (set to zero if omitted) 

\ Flag Byte: X'00'= Non-default image 

^ X'40'= Fold image 

X'60'= Fold image/ Default 
X'80'» Default image 

"7 UCS Image Name 

■^ UCS Image Name or Alias (1-4 character 
name, left-justified and padded to a 
4-character length with blanks, if necessary) 

■^ Length of this entry 



Figure 40. UCS Image Table Entry Fonnat 



Notes to Figure 40: 

1. This field is optional. 

2. This field is optional for the 4245 Printer. For the 3262 Model 5 and the 
4248, this field does not apply and is set to X' 00' . 
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Verifying the UCS Image 



For the 3262 Model 5 Printer, DEVICE=4248 should be specified in 
order to create the appropriate form of the image table entry. 

VLENGTH=(«7,n2,. . . «) 

specifies the length(s) of each line in the UCS verification display. The 
length of each line must be specified separately, even if all lines are of the 
same length. 

nl is the length of print line 1; n2 is the length of print line 2; /i is the 
length of the last print line. To display the complete image, the sum of the 
verification line lengths should equal 350. 

For details on the verification report, see "Verifying the UCS Image." 

The VLENGTH parameter is not valid for the 3262 Model 5 or 4248 
Printer. 

FOLD={VES|NO} 

indicates whether the UCS image is to be folded. 

YES 

indicates that the UCS image is to be folded. Allows printing only 
uppercase characters from either upper- or lowercase data codes. 
Folding continues until an UNFOLD comomand is received. 

NO 

indicates that the UCS image is not to be folded. This is the default. 



For the 1403 (with the UCS feature), 3203, 3211, 3262 Model 5, 4245, and 
4248 Printers, you can print the UCS image for visual verification using either of 
the following parameters: 

. InJCL: VCS-icharacier set code„VE^aFY) 

• In the SETPRT macro: VCS=icharacter set code„\) 

You can also use these parameters for the 3262 Model 5 and 4248 Printers. 
However, because the UCS image cannot be read directly from the 3262 Model 
5, or 4248, only the header information is printed. The verification display 
header appears in the format shown below. 



UCS IMAGE VERIFICATION image id [,FOLD] [description] 



image id 

The 1- to 4-character name of the UCS image. 

description 

The descriptive information supplied for this UCS image in the UCS 
image table. 
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The contents of the UCS image table UCS6 (IGGUCS6 macro), for the 4248 
Printer, are shown in Figure 42. 



Name 


Alias 


Default 


Description 


40E1 


40E1 


YES 


Default UCS unage 


40E1 


AN21 


NO 


4245 AN21 image 


40E1 


AN 


NO 


1403/3203 AN image 


40E1 


All 


NO 


3211 All image 


4101 


4101 


NO 


Nondefault UCS image 


4101 


HN21 


NO 


4245 HN21 image 


4101 


HN 


NO 


1403/3203 HN image 


4101 


Hll 


NO 


3211 Hll image 


41C1 


41C1 


NO 


Nondefault UCS image 


41C1 


GN21 


NO 


4245 GN21 image 


41C1 


Gil 


NO 


3211 Gil image 


4121 


4121 


NO 


Nondefault UCS image 


4121 


PL21 


NO 


4245 PL21 image 


4121 


FN 


NO 


1403/3203 PN image 


4121 


Pll 


NO 


3211 Pll image 


4181 


4181 


NO 


Nondefault UCS image 


4181 


TN21 


NO 


4245 TN21 unage 


4181 


TN 


NO 


1403/3203 TN unage 


4181 


Til 


NO 


3211 Til image 


4061 


4061 


NO 


Nondefault UCS image 


40C1 


40C1 


NO 


Nondefault UCS image 


4161 


4161 


NO 


Nondefault UCS image 


4161 


FC21 


NO 


4245 FC21 image 


4201 


4201 


NO 


Nondefault UCS image 


4201 


SN21 


NO 


4245 SN21 image 


4041 


4041 


NO 


Nondefault UCS image 


4041 


KA21 


NO 


4245 KA21 image 



Figure 42. UCS6 Image Table Contents 

Note: The unage tables for the 4245 and 4248 Printers include USA and Canada 
band IDs only. To support other national band IDs, you must modify the UCS 
image table. See "Adding or Modifying a UCS Image Table Entry" on page 213. 

The 3262 Model 5 Printer uses the 4248 UCS unage table, UCS6. However, no 
3262 Model 5 band names or aliases are provided by IBM in UCS6. In order to 
use 3262 Model 5 UCS images, you must add the names and aliases to UCS6 
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72 


//UCS6 


JOB . . . 




// 


EXEC ASMFCL, 




// 


FARM . ASM= ' NODECK , LOAD ' , 




// 


FARM . LKED= ' OL , RENT , REUS ' 




//SYSPRINT DD SYSOUT=A 




//ASM.SYSIN DD * 






TITLE 'UPDATED UCS6 IMAGE TABLE' 




UCS6 


CSECT 






IGGUCSIT NAME=40E1, 


X 




DEVICE=4248, 


X 




ALIAS=HN2 1 , 


X 




DEFAULT=YES , 


X 




DESCR='40E1 DEFAULT BAND' 






IGGUCS6 






END 




/* 






//LKED 


SYSLMOD DD DSN=SYS1 . IMAGELIB (UCS6) ,DISP=OLD, 




// 


SPACE= (OVERRIDE SECONDARY ALLOCATION) 





Notes to Example 2: 

1. This method creates a duplicate entry for 40E1 that becomes the first entry 
in the table. Because the table is searched sequentially, the new entry is 
always found before the old entry, thus effectively replacing the old entry. 

2. The RENT and REUS linkage editor attributes are required. 

3. Executing the ASMFCL procedure does not generate executable code. The 
assembler /linkage editor places the updated UCS image table into 
SYS1.IMAGELIB. 

4. The SPACE parameter is overridden because the ASMFCL cataloged 
procedure has secondary allocation specified. Elimination of the override 
causes the original secondary allocation amount to be used. 



^CB Images in SYSl.IMAGELIB 



Two standard FCB images, STDl and STD2, are included in SYSl.IMAGELIB 
during system generation for the following printers: 

3203 

3211 

3262 Model 5 

4245 

4248 

The 4248 and 3262 Model 5 Printers also accept FCBs that can be used with the 
3203, 3211, and 4245 Printers. (These are referred to as 3211 format FCBs.) 
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LIST 

produces a UCS image table entry based on the information 
supplied in other IGGUCSIT parameters. If LIST is selected or 
allowed to default, the NAME parameter must also be coded. 

DSECT 

produces a DSECT for a single UCS image table entry, similar to 
the sample entry shown in Figure 40 on page 210. If you code 
DSECT, all other parameters of IGGUCSIT are ignored. 

LIST is the default. 

NAMEss image name 

specifies the 1 to 4 character UCS image name. 

ALlASssimage alias 

specifies a 1 to 4 character alias name for the UCS image. If ALIAS is 
not specified, the image name coded in the NAME parameter will be 
entered in the UCS image table. 

DEFAULT=fyES|NO} 

indicates whether the new UCS image is to be used as a default value. 



YES 



NO 



indicates that this UCS image is a default. Default images are used 
by the system for jobs that do not request a specific image. 



indicates that this UCS image should not be used as a default. 



If the DEFAULT parameter is not specified, the new UCS image is not 
used as a default. 

DESCR-description 

specifies descriptive information about the new UCS image, description 
can be up to 32 EBCDIC or hexadecimal characters long. You cannot use 
EBCDIC and hexadecimal characters in combination. 

Descriptive information is placed in the header line of the verification 
display, following the real UCS image name. If you omit the DESCR 
parameter, no description appears in the display. For more information on 
the verification display, see "Verifying the UCS Image" on page 215. 

If VLENGTH is not specified for the 4245 Printer, the DESCR parameter 
is ignored. 

DEVICE«{4245|4248} 

specifies the type of device for which an image table entry is to be created. 

If you specify MF=LIST on the first mvocation of the IGGUCSIT macro, 
DEVICE defaults to 4245. The default for subsequent invocations is the 
printer type that you specified (or the default) on the first invocation. 
Table entries with different DEVICE specifications are not allowed. 
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FCB2STD2 CSECT 














DC X'80' 




DEFAULT 








DC AL1 (66) 


FCB IMAGE LENGTH 


= 66 




DC X' 000000' 


LINE 


1, 


2, 3 








DC x'or 


LINE 


4, 


CHANNEL ' 








DC X' 0000000000' 


LINE 


5, 


6, 7, 8, 


9 






DC X'02' 


LINE 


10. 


CHANNEL 


2 






DC X' 0000000000' 


LINE 


11 


12, 13, 


14, 


15 




DC X'03' 


LINE 


16 


CHANNEL 


3 






DC X' 0000000000' 


LINE 


17, 


18, 19, 


20, 


21 




DC X ' 04 ' 


LINE 


22 


CHANNEL 


4 






DC X' 0000000000' 


LINE 


23 


24, 25, 


26, 


27 




DC X'05' 


LINE 


28 


CHANNEL 


5 






DC X'OOOOOOOOOC 


LINE 


29 


30, 31, 


32, 


33 




DC X ' 06 ' 


LINE 


34 


CHANNEL 


6 






DC X' 0000000000' 


LINE 


35 


36, 37, 


38, 


39 




DC X'07' 


LINE 


40 


CHANNEL 


7 






DC X' 0000000000' 


LINE 


41 


42, 43, 


44, 


45 




DC X'08' 


LINE 


46 


, CHANNEL 


8 






DC X' 0000000000' 


LINE 


47 


48, 49, 


50, 


51 




DC X'OA' 


LINE 


52 


CHANNEL 


10 






DC X' 0000000000' 


LINE 


53 


, 54, 55, 


56, 


57 




DC X ' OB ' 


LINE 


58 


CHANNEL 


11 






DC X' 0000000000' 


LINE 


59 


60, 61, 


62, 


63 




DC X'OC 


LINE 


64 


CHANNEL 


12 






DC X'OO' 


LINE 


65 










DC X ' 1 9 ' 


LINE 


66 


CHANNEL 


9-END OF FCB 


IMAGE 


END 















Figure 44. Sample of the Standard FCB Image STD2 



Adding an FCB Image to the Image Library 



You may add a 321 1 -format FCB image to those that reside in 
SYSl.IMAGELIB, using the assembler and linkage editor. No executable code 
is generated; the assembler prepares DCs, and the linkage editor links them into 
SYSl.IMAGELIB. The new FCB image must be structured according to the 
following rules: 

1. The member name may not exceed eight bytes. The first four characters of 
the name must be FCB2. The characters that follow identify the FCB image 
and are referred to as the "image identifier" (ID). Any combination of valid 
assembler language characters can be used, with the exception of a single 
"C" or "U," because these are used by the system to recognize special 
conditions. The image identifier must be specified in the FCB keyword of a 
DD statement or in the SETPRT macro to load the image into the FCB 
buffer. 

2. The first byte of the FCB load module specifies whether the image is a 
default. (Default images may be used by the system for jobs that do not 
request a specific image.) Specify the following in the first byte: 

X'80' indicates a default image 
X*00' indicates a nondefault image 



Chapter?. Maintaining SYSl.IMAGELIB 219 



For more information about the UCS VERIFY parameters, see JCL Reference 
and Data Administration: Macro Instruction Reference. 



Examples of Adding to the UCS Image Table 



Example 1: Adding a New Band ID to the 4245 UCS Image Table (UCSS) 



In this example, the band name RPQl with description "RPQ BAND" is added 
to UCSS. In the UCS verification display, 7 lines of 50 characters each are 
printed. Macro IGGUCS5 causes the UCS image table source (as distributed by 
IBM) to be included in the table entry. 







72 


//UCS 5 


JOB . . . 




// 


EXEC ASMFCL, 




// 


FARM . ASM= ' NODECK , LOAD ' , 




// 


FARM . LKED= ' OL , RENT , REUS * 




//SYSPRINT DD SYSOUT=A 




//ASM. SYS IN DD * 






TITLE 'UPDATED UCSS IMAGE TABLE' 




UCSS 


CSECT 






IGGUCSIT NAME=RFQ1, 


X 




VLENGTH=(50,50,50,50,50,S0,S0) , 


X 




DESCR='RFQ BAND' 






IGGUCS5 






END 




/* 






//LKED 


SYSLMOD DD DSN=SYS1 . IMAGELIB (UCSS) ,DISF=OLD, 




// 


SFACE= (OVERRIDE SECONDARY ALLOCATION) 





Notes to Example 1 : 

1 . The RENT and REUS linkage editor attributes are required. 

2. Executing the ASMFCL procedure does not actually generate executable 
code. The assembler/linkage editor places the updated UCS image table 
intoSYSLIMAGELIB. 

3. The SPACE parameter is overridden here because the ASMFCL cataloged 
procedure has secondary allocation specified. Elimination of the override 
causes the original secondary allocation amount to be used. 



Example 2: Adding a New Default Entry to the 4248 UCS Image Table (UCS6). 



In the following example, the band name 40E1 with description "40E1 
DEFAULT BAND" is added to UCS6 and defined as a default band. An alias 
name, HN21, is also defmed for band 40E1. Macro IGGUCS6 causes the UCS 
image table source (as distributed by IBM) to be included in the table entry. 
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//ADDFCB 


JOB 


MSGLEVEL= 


1 




//STEP 


EXEC 


PROC=ASMFCL , PARM . ASM= ' NODECK , LOAD ' , 


// 




PARM . LKED 


= ' LI ST , OL , REFR , RENT , XREF ' 


//ASM.SYSIN 


DD 


* 






FCB2ID1 


CSECT 






♦THIS EXAMPLE 


IS FOR 


A FORM LENGTH OF ' 


11 INCHES WITH 8 LPI (88 LINES) 




DC 


X'80' 


THIS IS 


A DEFAULT IMAGE 




DC 


AL1 (89) 


LENGTH OF FCB IMAGE AND INDEXING BYTE 




DC 


X'BF' 


OFFSET ' 


15 CHARACTERS TO THE RIGHT 




DC 


X'10' 


8 LINES 


PER INCH-NO CHANNEL FOR LINE 1 




DC 


XL4 • • 


4 LINES 


NO CHANNEL 




DC 


X'01 ' 


CHANNEL 


1 IN LINE 6 




DC 


XL6 ' ' 


6 LINES 


NO CHANNEL 




DC 


X'02' 


CHANNEL 


2 IN LINE 13 




DC 


XL6 • ' 


6 LINES 


NO CHANNEL 




DC 


X'03' 


CHANNEL 


3 IN LINE 20 




DC 


XL6 • ' 


6 LINES 


NO CHANNEL 




DC 


X'04' 


CHANNEL 


4 IN LINE 27 




DC 


XL6 ■ ' 


6 LINES 


NO CHANNEL 




DC 


X'05' 


CHANNEL 


5 IN LINE 34 




DC 


XL6 • ' 


6 LINES 


NO CHANNEL 




DC 


X'06' 


CHANNEL 


6 IN LINE 41 




DC 


XL6 ' • 


6 LINES 


NO CHANNEL 




DC 


X'07' 


CHANNEL 


7 IN LINE 48 




DC 


XL6 ' • 


6 LINES 


NO CHANNEL 




DC 


X'08' 


CHANNEL 


8 IN LINE 55 




DC 


XL6 ' ' 


6 LINES 


NO CHANNEL 




DC 


X'09' 


CHANNEL 


9 IN LINE 62 




DC 


XL6 ' • 


6 LINES 


NO CHANNEL 




DC 


X'OA' 


CHANNEL 


10 IN LINE 69 




DC 


XL6 • • 


6 LINES 


NO CHANNEL 




DC 


X'OB' 


CHANNEL 


11 IN LINE 76 




DC 


XL6 • • 


6 LINES 


NO CHANNEL 




DC 


X'OC 


CHANNEL 


12 IN LINE 83 




DC 


XL4 ' ' 


4 LINES 


NO CHANNEL 




DC 


X'10' 


POSITION 88 LAST LINE IN IMAGE 




END 








/* 










//LKED.SYSLMOD 


DD 


DSNAME=SYS1 .IMAGELIB(FCB2ID1 ) ,DISP=OLD, 


// 




SPACE= 


(OVERRIDE SECONDARY ALLOCATION) 



Figure 45. Sample Code to Assemble and Add an FCB Load Module to SYSl.EVfAGELIB 



Notes to Figure 45: 

1. The RENT and REFR linkage editor attributes are required. 

2. Executing the ASMFCL procedure does not actually generate executable 
code. The assembler/linkage editor is used to place the FCB image into 
SYS1.IMAGELIB. 

3. The SPACE parameter is overridden here because the ASMFCL cataloged 
procedure has secondary allocation specified. Elimination of the override 
causes the original secondary allocation amount to be used. 
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STDl sets line spacing at 6 lines per inch for an 8-1/2 inch form; STD2 is a 
default FCB image that sets line spacing at 6 lines per inch for an 1 1-inch fonn. 
Channels for both images are evenly spaced, with Channel 1 on the fourth line 
and Channel 9 on the last line. See Figure 43 on page 218 and Figure 44 on 
page 219 for sample STDl and STD2 unages. 

The 3262 Model 5, the 4245, and the 4248 Printer each load a default FCB 
image into the buffer when they are powered on. The 3262 Model 5 default 
FCB image is an 1 1-inch form with 6 lines per inch, a Channel 1 on the third 
print line, and a Channel 12 on line 64. The 4245 default FCB image is an 
1 1-inch form with 6 lines per inch and a Channel 1 on the first print line. The 
4248 default FCB image is the last FCB image loaded. 

The standard FCB images STD3 is included in SYSl.IMAGELIB during system 
generation for the following printer: 

3800 

You should use the lEBIMAGE utility to create and modify FCB modules for 
the 3800 Printing Subsystem. You should also use it to create and modify FCB 
images for the 3262 Model 5 or 4248 Printer (4248 format FCBs). 

Note: FCB module CSECT names for the 3262 Model 5 and 4248 Printers 
must begm with the letters "FCB4" For information on ffiBIMAGE and the 
format of the 4248 FCB image, see Utilities. 



FCB2STD1 CSECT 














DC 


X'80' 


DEFAULT 








DC 


AL1 (48) 


FCB IMAGE LENGTH 


= 48 




DC 


X'OOOOOO' 


LINE 


^, 


2, 3 






DC 


x'or 


LINE 


4, 


CHANNEL 1 






DC 


X'OOOOOO' 


LINE 


5, 


6, 7 






DC 


X'02' 


LINE 


8, 


CHANNEL 2 


" 




DC 


X'OOOOOO' 


LINE 


9, 


10, 11 






DC 


X'03' 


LINE 


12, 


CHANNEL 


3 




DC 


X'OOOOOO' 


LINE 


13, 


14, 15 






DC 


X'04' 


LINE 


16, 


CHANNEL 


4 




DC 


X'OOOOOO' 


LINE 


17, 


18, 19 






DC 


X'05' 


LINE 


20, 


CHANNEL 


5 




DC 


X'OOOOOO' 


LINE 


21, 


22, 23 






DC 


X'06' 


LINE 


24, 


CHANNEL 


6 




DC 


X'OOOOOO' 


LINE 


25, 


26, 27 






DC 


X'07' 


LINE 


28 


, CHANNEL 


7 




DC 


X'OOOOOO' 


LINE 


29 


, 30, 31 






DC 


X'08' 


LINE 


32 


, CHANNEL 


8 




DC 


X'OOOOOO' 


LINE 


33 


, 34, 35 






DC 


X'OA' 


LINE 


36 


, CHANNEL 


10 




DC 


X'OOOOOO' 


LINE 


37 


, 38, 39 






DC 


X'OB' 


LINE 


40 


, CHANNEL 


11 




DC 


X'OOOOOO' 


LINE 


41 


, 42, 43 






DC 


X'OC 


LINE 


44 


, CHANNEL 


12 




DC 


X'OOOOOO' 


LINE 


45 


r 46, 47 






DC 


X'19' 


LINE 


48 


, CHANNEL 


9 -END OF 


FCB IMAGE 


END 















Figure 43. Sample of the Standard FCB Image STDl 
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Return Code 


Meaning 


8(X'08') 


Either SYSl.IMAGELIB does not exist on the volume to 
which the catalog pomts, or SYSl.IMAGELIB is not 
cataloged. 


12(X'0C') 


An error occurred in reading the catalog or VTOC. 



BLDL and LOAD are the only macros that may refer to the DCB built by the 
IMGLIB macro. 
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3. The second byte of the load module indicates the number of bytes to be 
transferred to the control unit to load the FCB image. This count includes 
the byte, if used, for the print position indexing feature. 

4. The third byte of the load module (the first byte of the FCB image) is either 
the print position indexing byte, or the lines-per-inch byte. The print 
position indexing byte is optional and, when used, precedes the 
lines-per-inch byte. The 3262 Model 5, 4245, and 4248 Printers accept and 
discard the index byte if it is present, because neither printer supports the 
indexing feature. A description of the print position indexing feature and its 
use will be found in IBM 3211 Printer, 3216 Interchangeable Train 
Cartridge, and 3811 Printer Control Unit Component Description and 
Operator's Guide. 

The special index flag in the third byte contains X'80' plus a binary index 
value, from 1 to 32 (the default is 1). This index value sets the left margin: 
1 indicates flush-left; any other value indicates a line indented that many 
spaces. 

The form image begins with the lines-per-inch (LPI) byte. The LPI byte 
defines the number of lines per inch (6 or 8) and also represents the first line 
of the page. 

Note: Printers controlled by JES2 require a channel 1 identifier here. 

Typically, the length of an FCB image is consistent with the length of the 
form it represents. For example, an 8-1/2 inch form to be printed at 6 LPI 
has an FCB image that is 51 bytes long (8-1/2 inches times 6 LPI). 

The LPI byte appears as follows: 

X'ln' sets 8 LPI 

X'On* sets 6 LPI 

5. All remaining bytes (lines) must contain X'On*, except the last byte, which 
must be X' In'. The letter n can be a hexadecimal value from 1 to C, 
representing a channel (one to 12), or it can be 0, which means no channel 
is indicated. 

In Figure 45 on page 221, an FCB load module is assembled and added to 
SYSl.IMAGELIB. The image defines a print density of 8 lines per inch on an 
1 1-inch form, with a right shift of 15 line character positions (1-1/2 inches). 
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Chapter 8. JES2 Support for the IBM 1403, 3203 Model 5, and 
3211 Printers 



UCS Alias Names 



The system assigns an alias for each installation-standard print chain not actually 
defined on a given printer. This provides JES2 with flexibility in scheduling 
printers for SYSOUT data sets. For example, a request for the 1403 TN train 
would be assigned the Tl 1 train if the data set were printed on a 321 1. The 
assigned alias names that follow the naming conventions currently used in 
SYSLIMAGELffiare: 

Image Alias 

UCSIAN UCSlAll 

UCSIHN UCSlHll 

UCSIPN UCSlPll 

UCSITN UCSlTll 

UCS2A11 UCS2AN 

UCS2H11 UCS2HN 

UCS2P1 1 UCS2PN,UCS2RN,UCS2QN 

UCS2T11 UCS2TN 

The image and alias names are mcluded in SYSl.IMAGELIB at system 
generation. 

Some trains, such as SN and Gl 1, do not have aliases because neither has an 
equivalent train on the other printer. An installation can assign an alias, if it so 
chooses. (For details about the ALIAS statement, see Linkage Editor and 
Loader User's Guide.) If an alias is supplied, JES2 will use it. If an alias is not 
supplied, an installation-defined SYSOUT class or a printer routing code 
(specified via the DEST parameter) should be used to assign the data set to the 
correct printer. If a SYSOUT class or a printer routing code is not used and if 
JES2 is directed to print a data set on a printer for which the proper image is not 
supplied, JES2 notifies the operator. The operator can then print the data set 
with a valid train or redirect the data set to the proper printer via the ' $E' 
command. 

If an installation defines a new train, it can supply an alias name for that train, 
via the linkage editor ALIAS statement, when including the image in 
SYS1.IMAGELIB. 
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Retrieving an FCB Image from SYSl.IMAGELIB 



If you want to modify an FCB image in virtual storage before loading it into a 
forms control buffer, you can use this sequence of macro instructions to read the 
FCB image into virtual storage. 

1. An IMGLIB macro instruction, along with the OPEN parameter 

2. A BLDL macro instruction to determine whether the FCB image you want 
is in the image library 

3. A LOAD macro instruction to load the image into virtual storage 

After the image has been read in, you should issue the IMGLIB macro 
instruction with the CLOSE parameter and the address of the DCB that was 
built by the first IMGLIB macro. A SETPRT macro instruction can be used to 
load the forms control buffer with the modified image. Printers other than the 
3800 require the use of an FCB entry in an exit list, as described in Data 
Administration Guide. 

The format of the BLDL and SETPRT macros is given in Data Administration: 
Macro Instruction Reference; the format of the LOAD macro is given in 
Supervisor Services and Macro Instructions. 

The format of the IMGLIB macro is shown below: 



[symboll 


IMGLIB 


|OPEN|CLOSE,fl^/i 



OPEN 

specifies that a DCB is to be built for SYSl.IMAGELIB and that 
SYSl.IMAGELIB is to be opened. The address of the DCB is returned in 
register 1. 

CLOSE 

specifies that SYSl.IMAGELIB is to be closed. 

addr 

specifies the RX-type address of the word that points to the DCB. If 
coded in the form (reg), the register in parentheses then contains the 
address of the DCB, not the address of the fullword. 

Return codes from the IMGLIB OPEN macro are shown below: 



Return Code 


Meaning 


O(X'OO') 


Operation successful. 


4(X'04') 


Either the vohime contammg SYSl.IMAGELIB is not 
mounted or a required catalog volume is not mounted. 
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Chapter 9. CATALOG, SCRATCH, and RENAME Dummy Modules 

I The detailed infonnation about installation-replaceable Catalog, Scratch, and 

I Rename dummy modules that appeared in this chapter has been moved to Data 

I Facility Product: Customization. 

I You can replace these modules to invoke special processing either before or after 

I CATALOG (SVC26), SCRATCH (SVC 29), or RENAME (SVC 30) 

I processing. 
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Chapter 8. JES2 Support for the IBM 1403, 3203 Model 5, and 
3211 Printers 



UCS Alias Names 



The system assigns an alias for each installation-standard print chain not actually 
defined on a given printer. This provides JES2 with flexibility in scheduling 
printers for SYSOUT data sets. For example, a request for the 1403 TN train 
would be assigned the Tl 1 train if the data set were printed on a 3211. The 
assigned alias names that follow the naming conventions currently used in 
SYSLIMAGELIBare: 

Image Alias 

UCSIAN UCSlAll 

UCSIHN UCSlHll 

UCSIPN UCSlPll 

UCSITN UCSlTll 

UCS2A11 UCS2AN 

UCS2H11 UCS2HN 

UCS2P1 1 UCS2PN,UCS2RN,UCS2QN 

UCS2T11 UCS2TN 

The image and alias names are included in SYSl.IMAGELIB at system 
generation. 

Some trains, such as SN and Gl 1, do not have aliases because neither has an 
equivalent train on the other printer. An installation can assign an alias, if it so 
chooses. (For details about the ALIAS statement, see Linkage Editor and 
Loader User's Guide.) If an alias is suppUed, JES2 will use it. If an alias is not 
supplied, an installation-defined SYSOUT class or a printer routing code 
(specified via the DEST parameter) should be used to assign the data set to the 
correct printer. If a SYSOUT class or a printer routing code is not used and if 
JES2 is directed to print a data set on a printer for which the proper image is not 
supplied, JES2 notifies the operator. The operator can then print the data set 
with a valid train or redirect the data set to the proper printer via the '$E' 
command. 

If an installation defines a new train, it can supply an alias name for that train, 
via the linkage editor ALIAS statement, when mcluding the image in 
SYS1.IMAGELIB. 
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The 3211 Indexing Feature 



JES2 supports the 321 1 Indexing Feature in two ways: 

1 . Specification of the INDEX parameter on the /*OUTPUT card. 

2. The extended FCB unage: 

JES2 supplies two special FCBs: FCB26 for 6 lines per inch and FCB28 for 
8 lines per inch (specified as FCB=6 and FCB=8, respectively). These 
FCBs contain a channel 1 indication in position 1, a special index flag in the 
third byte, and the number of lines per inch in the fourth byte of the image. 

The special index flag in the third byte of FCB26 and FCB28 contains 
X'80' plus a binary index value, in the range 1 to 32 (default=l). The 
index value sets the left margin (1 indicates flush-left position; other values 
cause indentation of the print line by N-1 positions). 

If any other FCB images are to be used by JES2, they must specify channel 
1 in position 1; otherwise, JES2 incorrectly positions the forms in the 
printer. (STDl and STD2 do not specify channel 1 in position 1 and 
therefore must not be specified, unless altered, for JES2.) 

If the third byte of any other FCB unage contains a data character 
(specifying the number of lines per inch) other than X'80', JES2 uses that 
specification and supplies an index value of 1. 



IBM 3203 Model 5 Printer 



The IBM 3203 Model 5 Printer is treated as a 321 1 Printer by JES2, except that 
the 3203 Model 5 does not support the 321 1 indexing feature, and any indexing 
commands from JES2 are ignored by the 3203 Model 5. The 3203 Model 5 uses 
321 1 FCB images and its own unique UCS images. UCS images are listed in 
System Generation. 
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Chapter 10. Specifying Buffer Numbers for DASD Data Sets 



The BUFNO keyword in the DCB macro and the BUFNO subparameter of the 
DCB kejrword in the DD statement determine how many buffers are allocated 
when accessing a partitioned or sequential data set using QSAM. The NCP 
keyword in the DCB macro determines how many un-GHECKed READ or 
WRITE macro instructions are allowed when accessing a sequential or 
partitioned data set using BSAM; one buffer is used for each READ or WRITE 
macro instruction. 

The sequential access method can construct a channel program to transfer as 
many as 30 buffers or 240000 bytes of data, whichever is less. If BUFNO or 
NCP is less than 30, no more than that number of buffers can be transferred 
with a single channel program. 

BUFNO is defaulted in OPEN to five if it is not specified for a QSAM DCB; 
NCP is defaulted to one in OPEN if it is not specified. The QSAM access 
method manages buffers. The user program must manage buffers when it uses 
BSAM. 



Performance Considerations 



Buffer number and block size influence the rate at which data can be transferred 
and the operating system overhead per block. The use of more buffers reduces 
(per block transferred) the EXCP and lOS overhead and the time waiting for the 
DASD device to seek to the requested cylinder and rotate to the requested 
record (device latency time). However, if more buffers are allocated than a 
program can effectively process, the virtual pages containing those buffers will 
be paged out, effectively adding to the system overhead for the job. A large 
number of buffers also cause a large amount of real storage to be allocated to 
the job while the data is being transferred. 

A job in a low-performance group may get swapped out more frequently than a 
higher priority job. The number of buffers allocated for the job contributes to 
the number of pages that have to be swapped out. 

Programs that access data sets with small block size (for example, 80) can easily 
make effective use of 30 buffers, which fit in, at most, two 4096"'byte pages. 
The advantage of 30 buffers over the default of five buffers is great: one 
channel program versus six channel programs to transfer 30 blocks. 

At the other end of the spectrum, usage of data sets with large blocking factors 
such as full-track blocking on 3350 or half-track blocking on 3380 can still be 
effective when only three or four buffers, rather than five or more, are specified. 
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DSN: Specify the Name of the DSCB 



DSN^addr 

DSN specifies the address of a 44--byte data set name of the DSCB to be 
accessed. 

DSN is required if ACCESS=READ or WRITE and the request is to read 
or write a DSCB. If a 140-byte DSCB is specified: 

• CVAF validity checks the storage location, but ignores the contents of 
the location. 

• You must specify an argument that points to an extent within the 
VTOC. 



BUFLIST: Specify One or More Buffer Lists 



BUFLIST=fl^r 

The BUFLIST keyword contains the address of a buffer list used to read 
or write a DSCB or VIRs. 



VERIFY: Verify that a DSCB is a Format-0 DSCB 



VERIFY=YES 

CVAF will verify that the DSCB is a format-0 DSCB before writing the 
DSCB. The first four bytes of the key will be compared with binary zeros. 
If the key does not start with four bytes of zeros, the DSCB will not be 
written and an error code will be returned. 

VERIFY=NO 

CVAF will not test the key of the DSCB. 

Note: VERIFY applies only when writing a 140-byte DSCB. VERIFY is 
ignored when a VIR is written. 



UCB I DEB: Specify the VTOC to Be Accessed 



VCB=(reg) 

Supplies the address of the UCB for the unit whose VTOC is to be 
accessed. An unauthorized caUer must not use this parameter. 

Note: Code the address of the UCB parameter as register (2-12). 
Coding an RX-Type address here gives you unpredictable results. 

If the address of a previously obtained I/O area is supplied through the 
lOAREA keyword, neither UCB nor DEB need be supplied. Otherwise, 
either a UCB or DEB must be supplied. If a UCB address is supplied, it 
will be overlaid in the CVPL by the UCB address present in the I/O area. 

DEB^addr 

Specifies the address of a DEB opened to the VTOC you want to access. 
CVAF does not allow output requests to the VTOC or VTOC index if 
you specify the DEB subparameter. If you are not authorized, you cannot 
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The slightly lower DASD performance and small increase in EXCP and lOS 
instruction costs should be more than offset by a reduction in paging or 
swapping in a constrained environment 

It can be seen that proper selection of buffer number can have a positive effect 
on the elapsed time of a job and the system overhead associated with the job. 
The DCB OPEN installation exit can use installation criteria for a default buffer 
number for QSAM DCBs (for a description of the OPEN installation exit, see 
Data Facility Product: Customization.) The NCP field of the DCB must be set by 
the program for BSAM DCBs. 
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ACCESS: Read or Write a DSCB or VIR(S), or Release Buffer Lists 

When ACCESS is READ or WRITE, a single DSCB is accessed for an indexed 
or nonindexed VTOC, or one or more VIRs are accessed for an indexed VTOC. 

ACCESS=READ 

Specifies that a single DSCB or one or more VIR(s) are to be read into a 
buffer whose address is in a buffer list. 

If the buffer list if for a DSCB, only one entry is used in the buffer list. 
The first entry with the skip bit set to zero and a nonzero buffer address is 
used. 

AH VIR(s) whose buffer list entry has the skip bit off will be read into a 
buffer. 

DSN and BUFLIST are required if ACCESS=READ for a DSCB buffer 
list. 

ACCESS= WRITE 

Specifies that a single DSCB or one or more VIRs are to be written from 
buffer(s) whose address is in a buffer list. 

WRITE is permitted with BRANCH=NO only if the caller is authorized 
byAPF. 

DSN and BUFLIST are required if ACCESS=WRITE for a DSCB buffer 
list. 

If any buffer list entry has its modified bit set, only those entries with the 
modified bit set will be written. If no modify bits are on, all VIRs will be 
written. 

ACCESS==RLSE 

Applies only to VIR buffer lists. It requests the release of one or more 
buffers m the VIR buffer list chain identified m the BUFLIST keyword, 
and the release of each buffer list for which all buffers are released. 

DSN and BUFLIST are not required if ACCESS=RLSE. 

Only buffers in the buffer list with the skip bit set to zero and with a 
nonzero buffer address are released. The buffer list is not released if any 
entry has the skip bit set to one. 

For an indexed VTOC, if ACCESS=sRLSE is coded, buffer lists and 
buffers pointed to by the BUFLIST keyword will be released, along with 
buffer lists supplied in the CVAF parameter list CVMRCDS and 
CVIRCDS fields. If the CVMRCDS or the CVIRCDS buffers are 
supplied in the BUFLIST field, either directly or indirectly through 
chaining, the keyword MAPRCDS=YES, IXRCDS=KEEP, or 
MAPRCDS=(NO,0), IXRCDS:=(NOKEEP,0) must be coded to prevent 
CVAF from freeing the buffers more than once. If buffers are released, 
the CVAF parameter list field pointing to the buffer list will be updated. 
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perform any asynchronous activity (such as EXCP, CLOSE, EOV) 
against the data set represented by the DEB because CVAF removes the 
DEB from the DEB table for the duration of the CVAF call. If you are 
not authorized (neither APF authorized nor in a system key) you must 
specify a DEB address, not a UCB, to CVAFDIR. See "Identifymg the 
Volume" on page 42 for further details. 

If you supply both the DEB and the UCB in the CVPL, the DEB address will be 
used and the UCB address will be overlaid in the CVPL by the UCB address in 
the DEB. 



lOAREA: Keep or Free the I/O Work Area 



lOAREA^KEEF 

Specifies the CVAF I/O area associated with the CVAF parameter list is 
to be kept upon completion of the CVAF request. IOAREA=KEEP may 
b6 coded with BRANCH=NO only if the caller is authorized (APF or 
system key). 

If IOAREA=KEEP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not any 
further VTOC access is required: for example, the recovery routine of the 
caller of CVAF. 

Coding IOAREA=KEEP allows subsequent CVAF requests to be more 
efficient, as certain initialization functions can be bypassed. Neither DEB 
nor UCB need be specified when a previously obtained CVAF I/O area is 
supplied; neither can they be changed. 

When IOAREA=KEEP is fu-st issued, CVAF returns the CVAF I/O area 
m the CVAF parameter list (CVIOAR). Subsequent calls of CVAF may 
use that same parameter list, and CVAF will obtain its I/O area from the 
CVIOAR. 

When processing on the current volume is finished, release all areas that 
were kept. 

IOAREA=(KEEP,£K/^r) 

Provides the address of a previously obtained I/O area. If a different 
CVAF parameter list is used, the previously obtained I/O area may be 
passed to CVAF by coding its address as the second parameter of the 
lOAREA keyword. 

IOAREA=NOKEEP 

Causes the work area to be freed upon completion of the CVAF request. 

IOAREA=(NOKEEP,a^Jr) 

Causes a previously obtained work area to be freed upon completion of 
the CVAF request. 
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MAPRCDS: Keep or Free MAPRCDS Buffer List and Buffers 



This keyword applies to an indexed VTOC only and specifies the disposition of 
the MAPRCDS buffer Ust and buffers. 

MAPRCDS=YES 

Specifies that the buffer list and buffers are to be retained at the end of 
processing. 

If no buffer list address is in the CVAF parameter list, CVAF will read 
the MAP VIRs into buffers it obtains. The buffer list that contains the 
address and RBAs of the VIRs can be accessed after processing from the 
CVAF parameter list field, CVMRCDS. The buffer list and VIR buffers 
are in your protect key: subpool if you are not authorized; 229 if you 
are. 

When processing on the current volume is finished, release all areas that 
were kept. 

MAPRCDS=(YES,aflf^r) 

If YES is coded and the buffer list address (CVMRCDS in CVAF 
parameter list) is supplied, VIRs are not read. 

The CVMRCDS buffer list used in CVAFDIR macro can be passed to 
another CVAF macro call through the MAPRCDS keyword. 

If MAPRCDS= YES is coded for a nonindexed VTOC, the function is 
performed, but an error code will be returned. 

MAPRCDS=NO 

If MAPRCDS=NO is coded, all the buffers without the skip bit on in the 
buffer list whose address is in the CVMRCDS field of the CVPL will be 
freed. If all the buffers are freed, the buffer list will also be freed. 

MAPRCDS=(NO,a^r) 

Causes buffer lists and buffers previously obtained by CVAF to be freed. 

You must free buffer lists and buffers obtained by CVAF. This can be done in 
one of three ways: 

• By codmg MAPRCDS^NO on the CVAFDIR macro that obtained the 
buffers 

• By coding MAPRCDS=NO on a subsequent CVAF macro 

• By coding CVAFDIR ACCESS=RLSE and providmg the address of the 
buffer list in the BUFLIST keyword 

Note: You must enqueue the VTOC and reserve the unit to maintain the 
integrity of MAP records read. 
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IXRCDS: Retain VIERS in Virtual Storage 

This keyword applies to indexed VTOCs only. 



IXRCDS=KEEP 

Specifies that VIERs read into storage are to be kept in virtual storage. 
The VIERs are retained even if processing cannot complete successfully. 
The CVAF parameter list in field CVIRCDS contains the address of a 
buffer list with the VIR buffer addresses and RBAs of the VERs read. 

The index search function will dynamically update the buffer list and, 
when necessary, obtain additional buffer lists and chain them together. 

If KEEP is specified and no buffer list is supplied to CVAF in the CVPL, 
CVAF will obtain a buffer list and buffers and read the first high-level 
VIER. The address of the buffer list is placed in the CVMICDS field of 
the CVPL. The first high-level VIER will be checked for the VXFHLV 
bit and to see whether the VXVISE bit is off. 

The buffer list and VIR buffers are in your protect key. The subpool is 
if you are not authorized; it is subpool 229 if you are. 

If IXRCDS=KEEP is coded for a nonindexed VTOC, a request to read or 
write a DSCB will be performed, but an error code will be returned. 

When processing on the current volume is finished, release all areas that 
were kept. 

IXRCDS=(KEEP,aJt/r) 

The index records buffer list address from one CVAF request is being 
passed to this CVAF parameter list by specifying its address as the second 
parameter in the IXRCDS keyword. 

IXRCDS=NOKEEP 

If NOKEEP is coded, the VIERs that are accessed (if any) are not 
retained. Furthermore, the buffer list supplied in the CVIRCDS field in 
the CVAF parameter list is released, as are all buffers found in the buffer 
list. If the skip bit is set in any entry in the buffer list, the buffer and 
buffer list will not be freed. 

IXRCDS=(NOKEEP,at/Jr) 

Specifies that previously accessed VIERs are not to be retained. 

You must free buffer lists and buffers obtained by CVAF. This can be done in 
one of three ways: 

• By coding IXRCDS=NOKEEP on the CVAFDIR macro that obtained the 
buffers 

• By coding IXRCDS=NOKEEP on a subsequent CVAF macro 

• By coding CVAFDIR ACCESS=RLSE and providing the address of the 
buffer list in the BUFLIST keyword 
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Note: You must enqueue the VTOC and reserve the unit to maintain the 
integrity of the VIERs read. 



BRANCH: Specify the Entry to the Macro 



BRANCH=(YES,SUP) 

Requests that the branch entry to CVAFDIR be used. You must be in 
supervisor state. Protect key checking is bypassed. 

An 18-word save area must be supplied if BRANCH=YES is coded. No 
lock may be held on entry to CVAF. SRB mode is not allowed. 

BRANCH=YES 

Equivalent to BRANCH=(YES,SUP), because SUP is the default when 
YES is coded. Protect key checking is bypassed. 

BRANCH=(YES,PGM) 

Requests the branch entry. You must be authorized by APF and be in 
problem state. Protect key checking is bypassed. 

BRANCH=NO 

Requests the SVC entry. You must be authorized by APF if any output 
operations are requested. Protect key checking is performed. 



MF: Specify the Form of the Macro 



This keyword specifies whether the Ust, execute, or normal form of the macro is 
requested. 

MF=I 

If I is coded or if neither L nor E is coded, the CVAF parameter list is 
generated and CVAF is called. This is the normal form of the macro. 

MF=L 

L indicates the list form of the macro. A parameter list is generated, but 
CVAF is not called. 

lVIF=(E,aJJr) 

E indicates the execute form of the macro. The CVAF parameter list 
whose address is in X'addr' can be modified by this form of the macro. 
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Return Codes from the CVAFDIR Macro 



On return from CVAF, register 1 contains the address of the CVPL (CVAF 
parameter list), and register IS contains one of the following return codes: 



Code Meaning 

00(X*00') The request was successful. However, if the CVAFDIR request is 

to read or write a DSCB and a VTOC index structure error is 
encountered, the CVSTAT field indicates the structure error 
encountered. (CVSTAT code descriptions are in 
Appendix C, "VTOC Index Error Message and Associated 
Codes" on page 297.) 

04(X ' 04 ' ) An error occurred. The CVSTAT field m the CVPL contams an 
indication of the cause of the error. (CVSTAT code descriptions 
are in Appendix C, "VTOC Index Error Message and Associated 
Codes" on page 297.) 

08(X*08*) Invalid VTOC index structure while processing a request to read 
or write a VTOC index record. The CVSTAT field ui the CVPL 
contains an indication of the cause of the error. (CVSTAT code 
descriptions are in Appendix C, "VTOC Index Error Message 
and Associated Codes" on page 297.) 

12(X'0C') The CVAF parameter list is not in your protect key or is invalid 
(the ID is invalid, or the length field is incorrect, or the CVFCTN 
field is invalid). The CVPL has not been modified. 

16(X* 10*) An I/O error was encountered. 



238 MVS/XA System-Data Administration 



CVAFDSM Macro 

Overview of the CVAFDSM Macro 

The CVAFDSM macro may be used for an indexed VTOC to: 

• Obtain one or more extents that describe unallocated space on the volume 
. Obtain a count of free DSCBs on the VTOC 

• Obtain a count of free VTOC index records in the VTOC index. 

Syntax 



[label] 


CVAFDSM 


ACCESS=MAPDATA 
,MAP=INDEX 1 VOLUME | VTOC 
lEXTEKTS=addr] 
[,MAPRCDS=VESi | (YES,addr) \ NO2 | 

(NO,addr)] 
lVCB=(reg) \ DEB=^addr] 
l,C0UNT=YES|N01 
[,CTAREA=fl^rl 
I,IOAREA=KEEP | (KEEP,addr) \ NOKEEP | 

(NOK¥EP,addr)\ 
|,BRANCH=NO 1 YES3 1 (YES,SUP) | (YES,PGM)I 
I,MF=I 1 L 1 (E,addr)] 



1 Default if MF=I. 

2 Default if MF=L or MF=(E,addr). 

3 Default is SUP if YES is coded. 

ACCESS=MAPDATA: Request Information from the Index Space Maps 

ACCESS=MAPDATA 

Obtains data from the index space maps. Three kinds of data are 
available: 

• The number of format-0 DSCBs (the data is obtained from the VTOC 
map of DSCBs) 

• The number of unallocated VIRs in the index (the data is obtained 
from the VTOC index map) 

• The number (and location) of extents of unallocated pack space (the 
data is obtained from the VTOC pack space map) 
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MAP: Identify the Map to Be Accessed 



MAP=B>fDEX 

Specifies that the VTOC index map (VDCM) is to be accessed and a count 
of unallocated VIRs returned. COUNT=sYES must also be coded. 

MAP=VOLUME 

Specifies that the VTOC pack space map (VPSM) is to be accessed and 
information on unallocated extents of pack space returned. 
EXTElSrrS=addr and COinsrr=NO must also be coded. 

]VIAP=VTOC 

Specifies that the VTOC map of DSCBs (VMDS) is to be accessed and a 
count of format-0 DSCBs returned. COUNT=YES must also be coded. 



EXTENTS: Identify Where Extents from the VPSM Are Returned 



EXTENTS=aJJr 

If one or more extents from the VPSM are requested, EXTENTS is the 
address of a 1-byte count field containing the number of S-byte extents 
that follow. In the first two bytes of the first 5-byte extent, you must 
supply the relative track address (RTA) at which CVAF should start the 
VPSM search. The first extent area is updated with information on the 
next free extent found that has a higher starting RTA than that supplied. 
Each subsequent extent area is filled in with information on free space 
extents (in ascending track address order). 

Information on free extents has the format, XXYYZ, where: 

• XX is the relative track address of the first track of the extent. 

• YY is the number of whole cylinders in the extent. 

• Z is the number of additional tracks in the extent. 

Only XX is supplied by the caller in the first extent area. CVAF will start 
searching the VPSM at relative track address XX. 

If all the unallocated extents in the VPSM are provided before filling in all 
the supplied extent areas, the remaining extent areas are set to zero. 
Register 15 is set to 4 on return, with the CVSTAT field in the CVPL set 
to X'20' to indicate end of data. 



MAPRCDS: Keep or Free MAPRCDS Buffer List and Buffers 



MAPRCDS=YES 

Specifies that the buffer list and buffers are to be retained at the end of 
the function. 

If YES is specified and no buffer list is supplied through the CVAF 
parameter list, CVAF will read the MAP VIRs into buffers obtained by 
CVAF. The buffer list that contains the address and RBAs of the VIRs 
can be accessed after the CVAF call from the CVAF parameter list field. 
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CVMRCDS. The buffer list and VIR buffers are in the caller's protect 
key: subpool if the caller is not authorized; subpool 229 if the caller is 
authorized. 

YES is the default if MF=I is specified or defaulted. 

When processing on the current volume is finished, release all areas that 
were kept. 

MAPRCDS=(YES,arf</r) 

If YES is coded, but the buffer list address (CVMRCDS in CVAF 
parameter list) is supplied, the VIRs are not read. 

The CVMRCDS buffer list from one CVAF call can be passed to another 
CVAF macro call through the MAPRCDS keyword. 

MAPRCDS=NO 

If MAPRCDS=NO is coded, the MAP records buffers and buffer list will 
be freed upon completion of the CVAFDSM function. 

NO is the default if MF=L is specified. 

MAPRCDS=(NO,a^^r) 

Causes buffer lists and buffers previously obtained by CVAF to be freed. 

Buffer lists and buffers obtained by CVAF must be freed by the caller. This can 
be done in one of three ways: 

• By codmg MAPRCDS=NO on the call that obtained the buffers. 

• By codmg MAPRCDS=NO on a subsequent CVAF call. 

• By calling CVAFDIR ACCESS^RLSE and providmg the buffer list in the 
BUFLIST keyword. 

K MF=(E,addr) is coded and MAPRCDS is not coded, the parameter list 
value of MAPRCDS is not changed. 

Note: You must enqueue the VTOC and reserve the unit to maintain the 
integrity of the MAP records read. 



UCB I DEB: Specify the VTOC to Be Accessed 



UCB=rreg; 

Supplies the address of the UCB for the unit whose VTOC is to be 
accessed. An unauthorized caller may not supply a UCB to CVAF. 

Note: Code the address of the UCB parameter only as register (2-12). 
Coding an RX-Type address here gives you unpredictable results. 

DEB^o^r 

Specifies the address of a DEB opened to the VTOC you want to access. 
CVAF does not aUow output requests to the VTOC or VTOC index if 
you specify the DEB subparameter. If you are not authorized, you cannot 
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perfonn any asynchronous activity (such as EXCP, CLOSE, EOV) 
against the data set represented by the DEB because CVAF removes the 
DEB from the DEB table for the duration of the CVAF call. If you are 
not authorized (neither APF authorized nor in a system key) you must 
specify a DEB address, not a UCB, to CVAFDSM. See "Identifying the 
Volume" on page 42 for further details. 

If a previously obtained CVAF I/O area is supplied through the lOAREA 
kejrword, neither UCB nor DEB need be supplied. Otherwise, either a UCB or 
DEB must be supplied. If a UCB address is supplied, it will be overlaid in the 
CVPL with the UCB address in the I/O area. 

If DEB and UCB are supplied in the CVPL, the DEB will be used, and the UCB 
address supplied will be overlaid in the CVPL with the UCB address obtained 
from the DEB. 



COUNT: Obtain a Count of Unallocated DSCBs or VIRs 

COUNT=YES 

Indicates that a count of unallocated DSCBs or VIRs in the designated 
space map is requested. MAP=:VTOC or MAP=INDEX must be 
specified if COUNT=:YES is coded. 

COUNT=NO 

Indicates that a count of unallocated DSCBs or VIRs is not desired but, 
rather, information on free space on the pack is desired. 
MAP=VOLUME must be coded if COUNT=NO is coded or defaulted. 

CTAREA: Supply a Field to Contain the Number of Format-0 DSCBs 

CTAREA=aJ^r 

Gives the address of a 4-byte field to contain the number of format^-O 
DSCBs when COUNT=YES, MAP=VTOC is specified; or the number of 
unallocated VIRs in the VTOC index when COUNT=YES, 
MAP=INDEX is specified. 



lOAREA: Keep or Free the I/O Work Area 



IOAR£A=KEEP 

Specifies that the CVAF I/O area associated with the CVAF parameter 
list is to be kept upon completion of the CVAF request. 
IOAREA=KEEP may be coded with BRANCH=NO only if the caller is 
authorized (APF or system key). 

If IOAREA=KEEP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not any 
further VTOC access is required: for example, the recovery routine of the 
caUer of CVAF. 

Coding IOAREA=KEEP allows subsequent CVAF requests to be more 
efficient, as certain initialization functions can be bypassed. Neither DEB 
nor UCB need be specified when a previously obtained CVAF I/O area is 
supplied; neither can they be changed. 
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When IOAREA=KEEP is first issued, CVAF returns the CVAF I/O area 
in the CVAF parameter list (CVIOAR). Subsequent calls of CVAF may 
use that same parameter list, and CVAF will obtain its I/O area from the 
CVIOAR. 

When processing on the current volume is finished, release all areas that 
were kept. 

IOAREA=(KEEP,a^f/r) 

Provides the address of a previously obtained I/O area. If a different 
CVAF parameter list is used, the previously obtained CVAF I/O area 
may be passed to CVAF by coding its address as the second parameter of 
the lOAREA keyword. 

IOAREA=NOKEEP 

Causes the work area to be freed upon completion of the CVAF request. 

IOAREA=(NOKEEP,aJt/r) 

Causes a previously obtained work area to be freed upon completion of 
the CVAF request. 



BRANCH: Specify the Entry to the Macro 



BRANCH=(YES,SUP) 

Requests that the branch entry to CVAFDIR be used. The caller must be 
in supervisor state. Protect key checking is bypassed. 

An 18-word save area must be supplied if BRANCH = YES is coded. No 
lock may be held on entry to CVAF. SRB mode is not allowed. 

BRANCH=YES 

Is equivalent to BRANCH=(YES,SUP), because SUP is the default when 
YES is coded. Protect key checking is b)rpassed. 

BRANCH=(YES,PGM) 

Requests the branch entry. The caller must be APF authorized and in 
problem state. Protect key checking is bypassed, 

BRANCH=NO 

Requests the SVC entry. The caller must be APF authorized if any output 
operations are requested. Protect key checking is performed. 



MF: Specify the Form of the Macro 



This keyword specifies whether the list, execute, or normal form of the macro is 
requested. 

MF=I 

If I is coded or if neither L nor E is coded, the CVAF parameter list is 
generated, as is code, to call CVAF. This is the normal form of the 
macro. 
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MF=L 

L indicates the list fotm of the macro. A parameter list is generated, but 
code to call CVAF is not generated. 

MF=(E,a^r) 

E indicates the execute form of the macro. The remote CVAF parameter 
list supplied as X'addr' is used in, and can be modified by, the execute 
form of the macro. 



Rettini Codes from the CVAFDSM Macro 



On return from CVAF, register 1 contains the address of the CVPL (CVAF 
parameter list), and register IS contains one of the following return codes: 



Code Meaning 

0(X*00*) The request was successful. 

4(X'04') End of data (CVSTAT is set to decimal 32), or an error was 

encountered. The CVSTAT field in the CVPL contains an indication 
of the cause of the error. (CVSTAT code descriptions are in 
Appendix C, "VTOC Index Error Message and Associated Codes" 
on page 297) 

8(X'08 •) Invalid VTOC index structure. CVSTAT contains an mdication of 
the cause of the error. (CVSTAT code descriptions are in 
Appendix C, "VTOC Index Error Message and Associated Codes" 
on page 297) 

12(X'0C' ) The CVAF parameter list is not in your protect key or is invalid (the 
ID is invalid, or the length field is incorrect, or the CVFCTN field is 
invalid). The CVPL has not been modified. 

16(X' 10') An I/O error was encountered. 
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CVAFFILT Macro 



Overview of the CVAFFILT Macro 



Syntax 



You may use the CVAFFILT macro to invoke the CVAF filter service. You 
may also use it to map or initialize the CVAF parameter list (CVPL). To 
accommodate the FSA address, the CVPL generated by CVAPFELT is 4 bytes 
longer than the CVPL generated by the other CVAF macros. CVAF filter 
retrieves data set DSCB chains from an indexed or nonindexed VTOC and 
places them in buffers you provide. You may request the DSCBs for a single 
partially qualified data set name or for a list of fully qualified data set names. 
You must identify a specific DASD device and provide both a filter criteria list 
(FCL) defining the request, and a CVAF buffer list (with buffers) for DSCB 
return. The format of the two elements of the FCL is shown in Figure 1 8 on 
page 54 and Figure 19 on page 56. The format of the buffer list is shown in 
"Buffer Lists" on page 45. CVAFFILT returns a complete set of DSCBs in the 
order that they are chained in the VTOC (format-1, format-2, then format-3). 

Note: Keywords coded on the Ust form of the macro need not be coded on the 
execute form. Keywords coded on one CVAFFILT call remain in effect for 
subsequent calls unless overridden, if you use the same CVAFFILT parameter 
list. 



[label] 


CVAFFILT 


[,ACCESS={READ | RESUME | RLSEJ] 

l^VnASl={addr\{reg)}\ 

[,|UCB= W^r 1 {reg)] | DEB={^JJr | (reg)\\ 

l¥CL={addr\{reg)\\ 

l,FLTAREA-{KEEP | YS.EPAaddr \ ireg)\ \ 

NOKEEP 1 NOKEEP, W^r | {reg)]]] 
I,IOAREA=|KEEP | KEEP,|a^r | {,reg)\ | 

NOKEEP 1 NOKEEP,|a^^r | {reg)\]\ 
I,BRANCH=|NO 1 YES | (YES,|SUP | PGMOH 
[,{MF=I 1 MF=D 1 MF=L | MY=(E,{addr \ {reg))]\ 



Note: For the first operand following CVAFFILT, you must not code the 
leading comma. 



Control Block Address Resolution: 



Keyword =dt^Jr | (reg) 

You, as the caller, either define or reference the control blocks needed by CVAF 
filter (caller-defined control blocks are: BUFLIST, CVPL, and FCL. 
Caller-referenced control blocks are: DEB, FLTAREA. lOAREA. and UCB). 
The CVAFFILT macro generates different instructions for keyword =addr and 
keyword=(reg) depending upon whether you are specifying a "defined" or 
"referenced" control block. 
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1 . When you specify any control block's address as ' (reg) • , the C VAFFILT 
macro assumes that the register specified contains that address. 

2. When you specify a "defined" control block's address as 'addr', the 
CVAFFELT macro assumes that the specified location is that of the control 
block itself. The macro generates a load address instruction (LA) to obtain 
the control block's address. 

3. When you specify a "referenced" control block's address as 'addr', the 
CVAFFILT macro assumes that the specified location is that of a f ullword 
containing the address of the control block. The macro generates a load 
mstruction (L) to obtain the control block's address. 

ACCESS: Retrieve or Resume Retrieving a DSCB, or Release FLTAREA and/or lOAREA 

ACCESS=READ 

Retrieves all DSCBs associated with the data set name(s) specified in the 
filter criteria list (FCL), placing them in your buffers. You can select 
(filter) the retrieved DSCBs by providing either a list of one or more fully 
qualified names, or a single partially qualified name, using single or double 
asterisk notation. (See the example of partially qualified names in 
"Examples of Partially Qualified Names for CVAFFILT" on page 250.) 

If the number of buffers is not large enough to hold all the requested 
DSCBs, CVAFFILT indicates this in the CVSTAT status byte of the 
CVAF parameter list (CVPL). You can resume the READ function by 
issuing a call with ACCESS=RESUME. See "Codes Put in the CVSTAT 
Field" on page 298. 

When selecting DSCBs by partially qualified name, CVAFFILT uses only 
the first data set name in the FCL list. You must set the FCLCOUNT 
count field in the FCL to • 1 • or CVAFFILT returns error code 63 in the 
CVSTAT status byte of the CVPL. The DSCBs returned by CVAFFILT 
may not be in sequence by data set name; however, the DSCBs for each 
data set are always in order (format- 1, format-2, format-3). 

When selecting DSCBs by fully qualified names, you may request that 
CVAF filter return the DSCBs for the selected data set names in the data 
set name order Implied by the FCL, See the FCLIORDR flag in 
Figure 1 8 on page 54. 

You should always test the status byte of each data set name in the FCL 
list to ensure successful completion (Some error conditions result in failure 
to return a data set's DSCBs). See the FCLDSNST byte in Figure 19 on 
page 56. 

ACCESS=RESUME 

Resumes a previously initiated READ or RESUME function that was 
terminated because you did not provide enough buffers to contain all the 
requested DSCBs. For the RESUME function to execute correctly, you 
must have coded the keyword FLTAREA=KEEP in each of the previous 
READ and RESUME function calls. 
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ACCESS=RLSE 

Releases the previously kept filter save area (FLTAREA) and/or CVAF 
I/O work area (lOAREA). 



UCB I DEB: Specify the VTOC to Be Accessed 



VCB^addr\(reg) 

Supplies the address of the UCB for the unit whose VTOC is to be 
accessed. If you are not authorized, you cannot supply a UCB to CVAF. 
CVAF returns CVSTAT '8' and return code '4' if you specify a UCB 
and you are not authorized. 

DEB=^addr\(reg) 

Specifies the address of a DEB opened to the VTOC you want to access. 
If you are not authorized, you cannot perform any asynchronous activity 
against the data set represented by the DEB (such as EXCP, CLOSE, 
EOV), because CVAF removes the DEB from the DEB table for the 
duration of the CVAF call. If you are not authorized (neither APF 
authorized nor in a system key) you must specify a DEB address, not a 
UCB, to CVAFFILT. See "Identifying the Volume" on page 42 for 
further details. 



BUFLIST: Specify a Buffer List 



BVFLlST=addr\(reg) 

The BUFLIST kejrword specifies the address of a buffer list used to read 
DSCBs. When you specify ACCESS=RLSE, the BUFLIST keyword is 
required for the standard form of the macro. See the format of the buffer 
list header and buffer list entry in Figure IS on page 46 and Figure 16 
on page 47, respectively. 



FCL: Specify a FUter Criteria List 



FCL=addr\(reg) 

The FCL keyword specifies the address of a filter criteria list. It is 
required when ACCESS^READ is specified on the standard form of the 
macro. The format of the two elements of the filter criteria list is shown 
in Figure 18 on page 54 and Figure 19 on page 56. 



FLTAREA: Keep or Free the Fflter Save Area 



FLTAREA^KEEP 

Specifies keeping the filter save area. You must code this operand if the 
RESUME function might be called later (to resume processing 
prematurely terminated because the number of caller-supplied buffers is 
not enough to contain all the returned DSCBs). 

CVAFFILT returns the address of the kept filter save area in the 
CVAFFILT parameter list (CVFSA field). If you specify the same 
parameter list in subsequent RESUME calls, CVAFFILT reuses the same 
filter save area. 
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Note: If you code this operand, you must subsequently issue CVAFFELT 
with ACCESS=RLSE to release the filter save area. 

FLTAREA=(KEEP,|fl£fJr | {reg)\) 

Specifies the address of a previously obtained filter save area. See the 
description of FLTAREA=KEEP operand for additional concerns. 

FLTAREA=NOKEEP 

Frees the filter save area upon completion of the CVAF request. 

FLTAREA=:(NOKEEP,WJr| (res)}) 

Frees a previously obtained filter save area upon completion of the CVAF 
request. 



lOAREA: Keep or Free the I/O Work Area 



IOAREA=KEEP 

Specifies keeping the CVAF I/O work area. For authorized callers, 
CVAFFILT returns the address of the kept I/O work area in the 
CVAFFILT parameter list (CVIOAR). If you specify the same parameter 
list in subsequent calls, CVAFFILT reuses the same I/O work area. 

Note: If you code this operand, you must subsequently issue CVAFFILT 
with ACCESS=RLSE to release the I/O work area. 

IOAREA=(KEEP,|fl</^r | {reg)\) 

Provides the address of a previously obtained filter save area. See the 
description of IOAREA=KEEP operand for additional concerns. 

IOAREA=NOKEEP 

Frees the filter save area upon completion of the CVAF request. 

IOAREA=(NOKEEP,W^r I (reg)O 

Frees a previously obtained CVAF I/O work area upon completion of the 
CVAF request. 



BRANCH: Specify the Entry to the Macro 



BRANCHING 

Requests the SVC (default) entry. Protect key checking is performed. 

BRANCH=YES 

Equivalent to BRANCH =( YES, SUP), because SUP is the default when 
you code YES. You must be in supervisor state. Protect key checking is 
bypassed, 

BRANCH=(YES,SUP) 

Requests the branch entry. You must be in supervisor state. Protect key 
checking is bypassed. You must supply an 18-word save area if you 
specify BRANCH=YES. You cannot hold a lock at entry to CVAF. You 
cannot be in SRB mode. 
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BRANCH=(YES,PGM) 

Requests the branch entry. You must be APF authorized and be in 
problem state. Protect key checking is bjrpassed. 



MF: Specify the Form of the Macro 



Specifies whether the DSECT, list, execute, or normal form of the macro is 
requested. You can be in either 24-bit or 31 -bit addressing mode. If you are not 
authorized, you must pass the address of a DEB built by OPEN. If you are 
authorized, you may pass either the DEB address or the UCB address. You 
must ensure that the volume is allocated and will remain mounted (for example, 
by dynamic allocation). 

MF=I 

Specifies the standard form of the macro. The CVAF parameter list is 
generated and CVAF is called. •NfF=I' is the default value. 

MF=D 

Specifies the DSECT form of the macro. The macro generates a request 
for the IC VAFPL macro to map the unique CVAF filter C VPL (4-bytes 
longer than standard CVPL). 

MF=L 

Specifies the list form of the macro. The CVAF parameter list is 
generated, but CVAF is not called. 

MF=(E,WJr|(reg)}) 

Specifies the execute form of the macro. The CVAF parameter list whose 
address is in 'addr' or 'reg' is used. You can modify the parameter list 
with this form of the macro. 



Return Codes from the CVAFFILT macro 



CVAF filter service does not issue any messages. Upon completion of a filter 
request, register 15 contains one of the following return codes: 



Code Meaning 

00(X ' 00 ' ) The request was successful. 

04(X'04*) Logical error; status information in C VST AT. 

08(X'08') Invalid VTOC structure. 

1 2(X ' OC • ) CVAFFILT parameter list in wrong key, or invalid. 

16(X'10') I/O error. 



Note: CVSTAT in the CVAF parameter list explains the status codes. See 
"Codes Put in the CVSTAT Field" on page 298 for a list of the status codes. 
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Examples of Partially Qualified Names for CVAFFILT 



CVAFFILT supports partially qualified data set names using single or double 
asterisk notation as shown below: 

• You may use a single asterisk to represent a single qualifier. For example, 
SYS 1.*. LOAD designates any data set with three qualifiers, the first being 
SYSl, the second being any qualifier, and the tturd being LOAD. 

• You may also use a single asterisk to represent zero or more unspecified 
characters. For example, LOAD.^LIB designates any data set having only 
two qualifiers, with LOAD being the first, and the second qualifier ending 
with the character string LIB (for example, LINKLIB). The asterisk may 
appear anywhere within the qualifier. You may use two single asterisks in 
the following way: LOAD.A*B*.LIB. CVAFFILT does not support the use 
of two or more single asterisks with any other character within a single 
qualifier (for example, LOAD.B**.LIB is invalid). 

• A double asterisk represents a place holder for zero or more qualifiers. For 
example, SYSl.** designates any data set having SYSl as its first or only 
qualifier. 
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CVAFSEQ Macro 



Overview of the CVAFSEQ Macro 

The CVAFSEQ macro may be used to: 

• Read an indexed VTOC sequentially in data-set-name (DSN) order 

• Read an indexed VTOC or a nonindexed VTOC in physical-sequential order 

Syntax 



[label] 


CVAFSEQ 


ACCESS=GT 1 GTEQ 

UBVFLlST=:addr] 

UDSN^addr] 

lVCB=(reg) | DEB=addr] 

I,DSNONLY=NO | YESJ 

lARG^addr] 

I,IOAREA=KEEP | (KEEP,a^r) | NOKEEP | 

(f^OKFEP,addr)] 
l,IXRCDS=KEEP 1 (KEEPfld^r) | NOKEEP | 

(NOKEEP,fl^r)I 
l,BRANCH=NO 1 YESi | (YES,SUP) | (YES,PGM)1 
I,MF=I|L|(E,fl^r)J 



1 If YES, default is SUP. 

ACCESS: Specify Relationship between Supplied and Returned DSN 

ACCESS=GT 

Specifies that the DSN or argument value is to be used to return a DSCB 
whose DSN or argument is greater than that supplied. 

ACCESS=GTEQ 

Specifies that the DSN or argument value is to be used to return a DSCB 
whose DSN or argument is greater than or equal to that supplied. 

Note: A CVAF call specifying ACCESS=GTEQ should be followed by 
an ACCESS=GT request, or the same DSCB or name will be returned. 

BUFLIST: Specify One or More Buffer Lists 

BUFLIST=a^^r 

The BUFLIST keyword supplies the address of a buffer list used to read 
or write DSCBs and VIRs. 
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DSN: Specify Access by DSN Order or by Physical-Sequential Order 

DSN^addr 

Specifies that access of an indexed VTOC is by DSN order. BUFLIST is 
required if DSNONLY=NO is coded or defaulted. 

DSN omitted 

If you omit the DSN keyword, access of an indexed or nonindexed VTOC 
is by physical-sequential order. BUFLIST is required. 

Note: If the order is physical-sequential, you must initialize the argument field 
in the first buffer list entry to zero or to the argument of the DSCB. If the 
argument is zero (BFLEARG=00), the read begins at the start of the VTOC. 
You must be authorized (APF or system key) to read multiple DSCBs with a 
single invocation of the CVAFSEQ macro. See "Initiating Physical-Sequential 
Access" on page 51 for more information. 

UCB I DEB: Specify the VTOC to Be Accessed 

VCB=(reg) 

Supplies the address of the UCB for the unit whose VTOC is to be 
accessed. An unauthorized caller may not supply a UCB to CVAF. 

Note: Code the address of the UCB parameter only as register (2-12). 
Coding an RX-type address here gives you unpredictable results. 

DEB=addr 

Specifies the address of a DEB opened to the VTOC you want to access. 
CVAF does not allow output requests to the VTOC or VTOC index if 
you specify the DEB subparameter. If you are not authorized, you cannot 
perform any asynchronous activity (such as EXCP, CLOSE, EOV), 
against the data set represented by the DEB because CVAF removes the 
DEB from the DEB table for the duration of the CVAF call. If you are 
not authorized (neither APF authorized nor in a system key), you must 
specify a DEB address, not a UCB, to CVAFSEQ. See "Identifying the 
Volume" on page 42 for further details. 

If a previously obtained CVAF I/O area is supplied through the lOAREA 
keyword, neither UCB nor DEB need be supplied. 

Otherwise, either a UCB or DEB must be supplied. If a UCB address is 
supplied, it will be overlaid in the CVPL with the UCB address in the I/O area. 

If you specify both DEB and UCB in the CVPL, the DEB will be used, and the 
UCB address supplied will be overlaid in the CVPL with the UCB address 
obtained from the DEB. 
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DSNONLY: Specify That Only the Data Set Name Be Read 

This keyword is applicable only to accessing an indexed VTOC in DSN order. 

DSNONLY=NO 

Requests that the data set name be obtained from the VTOC index and 
the DSCB be read into a buffer supplied through the BUFLIST keyword. 
BUFLIST is required. 

DSNONLY=YES 

Requests that only the data set name be obtained from the VTOC index. 
If the ARG keyword is coded, the argument of the DSCB is returned. 

ARG: Specify Where the Argument of the DSCB Is to Be Returned 

This keyword is applicable only to accessing an indexed VTOC in DSN order 
with DSNONLY=YES coded. 

ASLG=addr 

Provides the address of the 5-byte area where the CCHHR of each data 
set name in the VTOC index is returned when DSNONLY=YES is coded. 

lOAREA: Keep or Free the I/O Work Area 

IOAREA»K£EP 

Specifies that the CVAF I/O area associated with the CVAF parameter 
list is to be kept upon completion of the CVAF request. 
IOAREA=KEEP may be coded with BRANCH=NO only if the caller is 
authorized (APF, or system key). 

If IOAREA=KEEP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not any 
further VTOC access is required: for example, the recovery routine of the 
caller of CVAF. 

Coding IOAREA=KEEP allows subsequent CVAF requests to be more 
efficient, because certain initialization functions can be bypassed. Neither 
DEB nor UCB need be specified when a previously obtained CVAF I/O 
area is supplied; neither can they be changed. 

When IOAREA=KEEP is first issued, CVAF returns the CVAF I/O area 
in the CVAF parameter list (CVIOAR). Subsequent calls of CVAF may 
use that same parameter list, and CVAF will obtain its I/O area from the 
CVIOAR. 

When processing on the current volume is f mished, release all areas that 
were kept. 

IOAR£A=(KEEP,a^^r) 

Provides the address of a previously obtained I/O area. If a different 
CVAF parameter list is used, the previously obtained CVAF I/O area 
may be passed to CVAF by coding its address as the second parameter of 
the lOAREA keyword. 
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IOAREA=:NOKEEP 

Causes the work area to be freed upon completion of the CVAF request. 

IOAREA=(NOKEEP,a^/</r) 

Causes a previously obtained work area to be freed upon completion of 
the CVAF request. 



IXRCDS: Retain VIERs in Virtual Storage 

This keyword applies to an indexed VTOC only. 



IXRCDS=KEEP 

Specifies that the VIERs read into storage during the CVAF function are 
to be kept in virtual storage. The VDERs are retained even if the index 
function is unsuccessful. The VTERs are accessed from the CVAF 
parameter list (CVIRCDS). CVIRCDS is the address of a buffer list 
containing the VIR buffer addresses and RBAs of the VIERs read. 

Index search function will dynamically update the buffer list and, when 
necessary, obtain additional buffer lists and chain them together. 

If KEEP is specified and no buffer list is supplied to CVAF in the CVPL, 
CVAF will obtain a buffer list and buffers and read the first high-level 
VIER. The address of the buffer list is placed in the CVIRCDS field of 
the CVPL. The first high-level VIER will be checked for the VXFHLV 
bit and to see if the VXVISE bit is off. 

The buffer list and VIR buffers are in the caller's protect key. The 
subpool is if the caller is not authorized; subpool 229 if the caller is 
authorized. 

If IXRCDS=KEEP for an nonindexed VTOC, a request to read a DSCB 
may be performed, but an error code will be returned. 

When processing on the current volume is finished, release all areas that 
were kept. 

IXRCDS=(KEEP,a^^r) 

The CVIRCDS from one CVAF call can be passed to another CVAF 
parameter list by specifying the address as the second parameter in the 
IXRCDS keyword. 

IXRCDS^NOKEEP 

If NOKEEP is coded, the VIERs that are accessed (if any) are not 
retained. Furthermore, the buffer list supplied in the CVIRCDS field in 
the CVAF parameter list is released, as are all buffers found in the buffer 
list. If the skip bit is set in any entry in the buffer list, the buffer and 
buffer list will not be freed. 

IXRCDS=(NOKEEP,aJJr) 

Specifies that previously accessed VIERs are not to be retained. 

You must free buffer lists and buffers obtained by CVAF. This can be done in 
one of three ways: 
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• By coding IXRCDS=NOKEEP on the CVAFSEQ macro that obtained the 
buffers 

• By coding IXRCDS=NOKEEP on a subsequent CVAF macro 

• By coding CVAFDIR ACCESS=RLSE and providing the address of the 
buffer list in the BUFLIST keyword 

Note: You must enqueue the VTOC and reserve the unit to maintain the 
integrity of the VIERs read. 



BRANCH: Specify the Entry to the Macro 



BRANCH=(YES,SUP) 

Requests that the branch entry to CVAFDIR be used. The caller must be 
in supervisor state. Protect key checking is bypassed. 

An 18-word save area must be supplied if BRANCH=YES is coded. No 
lock may be held on entry to CVAF. SRB mode is not allowed. 

BRANCH=YES 

Is equivalent to BRANCH=(YES,SUP), because SUP is the default when 
YES is coded. Protect key checking is bypassed. 

BRANCH=(YES,PGM) 

Requests the branch entry. The caller must be APF authorized and in 
problem state. Protect key checking is bypassed. 

BRANCH=NO 

Requests the SVC entry. The caller must be APF authorized if any output 
operations are requested. Protect key checking is performed. 



MF: Specify the Form of the Macro 



This keyword specifies whether the list, execute, or normal form of the macro is 
requested. 

MF=I 

If I is coded, or neither L nor E is coded, the CVAF parameter list is 
generated, as is code, to call CVAF. This is the normal form of the 
macro. 

MFr=L 

L indicates the list form of the macro. A parameter list is generated, but 
code to call CVAF is not generated. 

MF=(E,a</Jr) 

E indicates the execute form of the macro. The remote CVAF parameter 
list supplied as 'addr' is used in and can be modified by the execute form 
of the macro. 
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Return Codes from the CVAFSEQ Macro 



On return from CVAF, register 1 contains the address of the CVPL (CVAF 
parameter list), and register IS contains one of the following return codes: 



Code Meaning 

00(X ' 00 ' ) The request was successful. 

04(X'04') End of data (CVSTAT is set to decimal 32), or an error was 

encountered. The CVSTAT field in the CVPL contains an mdication 
of the cause of the error. Error descriptions are in 
Appendix C, "VTOC Index Error Message and Associated Codes" 
on page 297. 

08(X'08') Invalid VTOC index structure. CVSTAT contains an mdication of the 
cause of the error. Error descriptions are in Appendix C, "VTOC 
Index Error Message and Associated Codes" on page 297. 

12(X'0C') The CVPL (CVAF parameter list) is not in your protect key, or is 
invalid (the ED is invalid, or the length field is incorrect, or the 
CVFCTN field is invalid). The CVPL has not been modified. 

1 6(X* 1 ' ) An I/O error was encountered. 
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CVAFTST Macro 



Overview of the CVAFTST Macro 



The CVAFTST macro determines whether the system supports an indexed 
VTOC, and, if it does, whether the VTOC on the unit whose UCB is supplied is 
indexed or nonindexed. 

You will get a return code of 12 if CVAFTST cannot determine whether an 
indexed or nonindexed VTOC is on the unit's volume. You should not receive a 
return code of 12 from CVAFTST if you have opened a data set (including the 
VTOC) on the volume. 

You need no authorization to issue the CVAFTST macro. 



Syntax 



[labell 


CVAFTST 


VCB^(reg) 



UCB: Specify the VTOC to Be Tested 



VCB==(reg) 

Supplies the address of the UCB for the volume whose VTOC is to be 
tested. 

Note: Code the address of the UCB parameter only as register (2-12), 
Coding an RX-tjrpe address here gives you unpredictable results. 
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Return Codes from the CVAFTST Macro 

On return from CVAF, register 15 contains one of the following return codes: 



Code Meaning 

O(X'OO') The system does not support an indexed VTOC. The volume should be 
considered to have a nonindexed VTOC. The UCB was not inspected 
to determine its validity or status. 

4(X'04') The system supports an indexed VTOC, but the volume has a 
nonindexed VTOC. 

8(X'08') The system supports an indexed VTOC and the volume has an indexed 
VTOC. 

12(X*0C') The system supports an indexed VTOC, but the volume is not mounted 
or the VIB is not initialized for it; thus, the status (indexed or 
nonindexed) of the VTOC cannot be determined. 

16(X' lO*) The system supports an indexed VTOC, but the unit is not a DASD or 
has a VIO UCB, or the UCB address is invalid. 
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Appendix B. Examples of VTOC Access Macros 



The examples that follow are partial assembler listings that include expansions of 
each VTOC access macro. The expansions are provided to show how the 
VTOC macros can be substituted for existing procedures. 



Example 1: Using the CVAFDIR Macro with an Indexed or 
Nomndexed VTOC 

This example uses the CVAFDIR macro to read a DSCB of a given data set 
name and determines whether the DSCB is for a partitioned data set. The 
address of the 44-byte data set name is supplied to the program in register 5 
(labeled RDSN m the example). The address of a DEB open to the VTOC is 
supplied to the program in register 4 (labeled RDEB in the example). 

The buffer Ust is in the program and is generated by the ICVAFBFL macro. The 
DSCB buffer is in the program and is generated by the BECSDSLl macro. 

EXAMPLE 1 CSECT 

STM 14,12,12(RSAVE) 

BALR 12,0 

USING *,12 

ST RSAVE , SAVEAREA+4 

LA RWORK,SAVEAREA 

ST RWORK ,8{, RSAVE ) 

LR RSAVE, RWORK 

* 

* REGISTERS 

* 

REG1 EQU 1 REGISTER 1 

RWORK EQU 3 WORK REGISTER 

RDEB EQU 4 DEB ADDRESS 

RDSN EQU 5 ADDRESS OF DATA SET NAME 

RSAVE EQU 13 SAVE AREA ADDRESS 

REGIS EQU 15 RETURN CODE REGISTER 15 
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******** 

* 

* 
******** 

PDSRTN 
NOTFND 
NOTPDS 
UNEXPECD 

He ****** « 

* 



RETURN CODES 

EQU DATA SET A PDS RETURN CODE 

EQU 4 DATA SET NOT FOUND RETURN CODE 

EQU 8 DATA SET NOT A PDS RETURN CODE 

EQU 12 UNEXPECTED ERROR RETURN CODE 

READ DSCB INTO DS1FMTID. 

DATA SET NAME ADDRESS SUPPLIED IN RDSN. 
ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB. 
DETERMINE IF DATA SET IS A PARTITIONED DATA SET. 
THIS PROGRAM IS NEITHER REENTRANT NOR REUSABLE. 



XC 

01 

MVI 

LA 

ST 

01 

MVI 



BUFLIST(BFLHLN+BFLELN) ,BUFLIST ZERO BUFFER LIST 

BFLHFL,BFLHDSCB 

BFLHN0E,1 

RW0RK,DS1FMTID 

RWORK,BFLEBUF 

BFLEFL,BFLECHR 

BFLELTH,DSCBLTH 



MVC DS1DSNAM,0(RDSN) 



DSCBS TO BE READ WITH BUFFER LIST 
ONE BUFFER LIST ENTRY 
ADDRESS OF DSCB BUFFER 
PLACE IN BUFFER LIST 
CCHHR OF DSCB RETURNED BY CVAF 
DATA PORTION OF DSCB READ - DSN « 
SUPPLIED IN CVPL 

MOVE IN DATA SET NAME TO WORKAREA 
CVAFDIR ACCESS=READ , DSN=DS 1 DSNAM, BUFLIST=BUFLIST , DEB= (RDEB) 

LOAD CVPL LIST ADDRESS 

START OF CVPL 

EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION CODE 

STATUS INFORMATION 

FIRST FLAG BYTE 

SECOND FLAG BYTE 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VI XM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 

STORE DEB PTR IN PARM LIST 

ADDRESSABILITY TO CVPL 
ANY ERROR 
BRANCH IF NOT 



+ 


CNOP 


0,4 


+ 


BAL 


1,ICV1E 


+ICV1S 


EQU 


* 


+ 


DC 


CL4 • CVPL • 


+ 


DC 


AL2(ICV1E-ICV1S) 


+ 


DC 


XLI'Or 


+ 


DC 


XLI'OO' 


+ 


DC 


B'OOOOOOOO' 


+ 


DC 


B' 00000000' 


+ 


DC 


H'O' 


+ 


DC 


A(0) 


+ 


DC 


A(DSIDSNAM) 


+ 


DC 


A(BUFLIST) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ICV1E 


EQU 


* 


+ 


ST 


RDEB, 36 (,1) 


+ 


SVC 


139 




USING CVPL, REG 1 




LTR 


REGIS, REGIS 




BZ 


NOERROR 
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* 

* DETERMINE WHAT ERROR IS 
* 

C REG15,ERROR4 IS RETURN CODE 4 

BNE OTHERERR BRANCH IF NOT 4 

CLI CVSTAT,STAT001 IS IT DATA SET NAME NOT FOUND? 

BNE OTHERERR BRANCH IF NOT 

DROP REG1 ADDRESSABILITY TO CVPL NOT NEEDED 

* DATA SET NAME NOT FOUND 

L RSAVE,4(,RSAVE) 

RETURN (14,12), RC=NOTFND SET UP DATA SET NOT FOUND ERROR 
+ LM 14,12,12(13) RESTORE THE REGISTERS 

+ LA 15,NOTFND(0,0) LOAD RETURN CODE 

+ BR 14 RETURN 

NOERROR EQU * DSCB READ 

MVC F1CCHHR,BFLEARG MOVE CCHHR OF FORMAT 1/4 DSCB TO ■< 

WORKAREA 

CLI DS1FMTID,C'4' IS DSCB A FORMAT 4 DSCB 

BE N0TF1 BRANCH IF YES. NOT A FORMAT 1 

TM DS 1 DSORG , DS 1 DSGPO IS FORMAT 1 DSCB FOR PARTITIONED * 

DATA SET 

BO PDS BRANCH IF PDS 

N0TF1 EQU * DSCB IS NOT A PDS 

L RSAVE,4(,RSAVE) 

RETURN (14, 12) ,RC=NOTPDS SET UP NOT PDS RETURN CODE 
+ LM 14,12,12(13) RESTORE THE REGISTERS 

+ LA 15,NOTPDS(0,0) LOAD RETURN CODE 

+ BR 14 RETURN 

PDS EQU * DATA SET IS PARTITIONED 

L RSAVE,4(,RSAVE) 

RETURN (14,12), RC=PDSRTN SET UP PDS RETURN CODE 
+ LM 14,12,12(13) RESTORE THE REGISTERS 

+ LA 15,PDSRTN(0,0) LOAD RETURN CODE 

+ BR 14 RETURN 

OTHERERR EQU * UNEXPECTED ERROR 

L RSAVE,4(,RSAVE) 

RETURN (14,12), RC=UNEXPECD 
+ LM 14,12,12(13) RESTORE THE REGISTERS 

+ LA 15,UNEXPECD(0,0) LOAD RETURN CODE 

+ BR 14 RETURN 

ERR0R4 DC F'4' ERROR RETURN CODE 4 

BUFLIST ICVAFBFL DSECT=NO BUFFER LIST 

+♦ BUFFER LIST HEADER 

+BUFLIST DS OF BUFFER LIST HEADER 

+BFLHNOE DS XLI NUMBER OF ENTRIES 
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+BFLHFL 


DS 


XL1 


+ 


ORG 


BFLHFL 


+BFLHKEY 


DS 


XL1 


+BFLHVIR 


EQU 


X'08' 


+BFLHDSCB 


EQU 


X'04' 


+ 


DS 


XL1 


+BFLHSP 


DS 


XL1 


+BFLHFCHN 


DS 


A 


+* 






+BFLHLN 


EQU 


♦-BUFLIST 



+* BUFFER LIST ENTRY 



KEY AND FLAG BYTE 

PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 

BUF. LIST ENTRIES DESCRIBE DSCBS 

RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 

FORWARD CHAIN PTR TO NEXT BUF. 

LIST 

LENGTH OF BUFFER LIST HEADER 



+BFLE 


DS 


OF 


+BFLEFL 


DS 


XL1 


+BFLERBA 


EQU 


X'80' 


+BFLECHR 


EQU 


X'40' 


+BFLETTR 


EQU 


X'20' 


+BFLEAUPD 


EQU 


X'10' 


+BFLEMOD 


EQU 


X'08' 


+BFLESKIP 


EQU 


X'04' 


+BFLEIOER 


EQU 


X'02' 


+ 


DS 


XL1 


+BFLELTH 


DS 


XL1 


+* 






+BFLEARG 


DS 


XLS 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XL3 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL4 


+BFLEBUF 


DS 


A 


+BFLELN 


EQU 


♦-BFLE 




IECSDSL1 (1) 


+IECSDSL1 


EQU 


* 


+IECSDSF1 


EQU 


IECSDSL1 


+DS1DSNAM 


DS 


CL44 


+DS1FMTID 


DS 


CL1 


+DS1DSSN 


DS • 


CL6 


+DS1V0LSQ 


DS 


XL2 


+DS1CREDT 


DS 


XL3 


+DS1EXPDT 


DS 


XL3 


+DS1N0EPV 


DS 


XL1 


+DS1N0BDB 


DS 


XL1 


+* 






+ 


DS 


XL1 


+DS1SYSCD 


DS 


CL13 


+ 


DS 


XL7 



BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

'TTR' OF ARGUMENT 

•RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
FORMAT 1 DSCB DATA SET NAME AND 
BUFFER 
FORMAT 1 DSCB 

DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 
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+DS1DS0RG 
+♦ 

+DS1DSGIS 
+* 

+DS1DSGPS 
+* 

+DS1DSGDA 
+DS 1 DSGCX 
+* 
+* 

+DS1DSGP0 
+DS1DSGU 
+* 
+* 
+* 
+ * 

+DS 1 DSGGS 
+DS 1 DSGTX 
+DS1DSGTQ 
+* 

+DS1ACBM 
+DS1DSGTR 
+ * 
+* 

+DS1RECFM 
+DS10PTCD 
+DSlBLkL 
+DS1LRECL 
+DS1KEYL 
+DS1RKP 
+DS1DSIND 
+DS 1 SCALO 
+DS 1 LSTAR 
+DS1TRBAL 
+ 

+DS1EXT1 
+* 
+ * 
+* 
+* 

+DS1EXT2 
+DS1EXT3 
+DS 1 PTRDS 
+DS1END 
DSCBLTH 
F1CCHHR 
SAVETUIEA 
CVPL 



DS XL2 DATA SET ORGANIZATION 

FIRST BYTE OF DS1DS0RG 
EQU X'80' IS - INDEXED SEQUENTIAL 301 A 

ORGANIZATION 
EQU X'40' PS - PHYSICAL SEQUENTIAL 301 A 

ORGANIZATION 
EQU X'20' DA - DIRECT ORGANIZATION aOlA 

EQU X'lO' CX - BTAM OR QTAM LINE GROUP 301 A 

EQU X'08' RESERVED 301 A 

EQU X'04' RESERVED 301 A 

EQU X'02' PO - PARTITIONED ORGANIZATION 301 A 

EQU X'OV U - UNMOVABLE, THE DATA 301 A 

CONTAINS LOCATION DEPENDENT 

INFORMATION 



EQU X'80' 

EQU X ' 40 ' 

EQU X'20' 

EQU X ' 1 • 

EQU X'OB' 

EQU X ' 04 ' 

EQU X'02' 

EQU X ' 1 • 

DS XL1 

DS XL1 

DS XL2 

DS XL2 

DS XL1 

DS XL2 

DS XL1 

DS XL4 

DS XL3 

DS XL2 

DS XL2 

DS XL10 

FIRST BYTE 

SECOND BYTE 

THIRD - SIXTH BYTES 

SEVENTH - TENTH BYTES 

DS 

DS 

DS 

EQU 



SECOND BYTE OF DS1DS0RG 

GS - GRAPHICS ORGANIZATION 301 A 

TX - TCAM LINE GROUP 301 A 

TQ - TCAM MESSAGE QUEUE 301 A 

RESERVED 301 A 

ACCESS METHOD CONTROL BLOCK 301 A 

TR - TCAM 3705 301 A 

RESERVED 301 A 

RESERVED 301 A 

RECORD FORMAT 

OPTION CODE 

BLOCK LENGTH 

RECORD LENGTH 

KEY LENGTH 

RELATIVE KEY POSITION 

DATA SET INDICATORS 

SECONDARY ALLOCATION 

LAST USED TRACK AND BLOCK ON TRACK 

BYTES REMAINING ON LAST TRACK USED 

RESERVED 

FIRST EXTENT DESCRIPTION 

EXTENT TYPE INDICATOR 

EXTENT SEQUENCE NUMBER 

LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 

THIRD EXTENT DESCRIPTION 

POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 



EQU 

DS 

DS 



XL10 
XL10 
XLS 

* 

♦-lECSDSLI-L'DSIDSNAM LENGTH OF DATA PORTION OF DSCB 
XLS CCHHR OF DSCB 

18F SAVE AREA 



ICVAFPL 



CVPL MAPPING MACRO 



+* CVAF PARAMETER LIST 



+CVPL DSECT 

+ DS OF 

+CVLBL DS CL4 

+CVLTH DS H 



CVAF PARAMETER LIST 

EBCDIC 'CVPL' 
LENGTH OF CVPL 
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+CVFCTN 


DS 


XL1 


+CVDIRD 


EQU 


X'01 ' 


+CVDIWR 


EQU 


X'02' 


+CVDIRLS 


EQU 


X'03' 


+CVSEQGT 


EQU 


X'04' 


+CVSEQGTE 


EQU 


X'05' 


+CVDMIXA 


EQU 


X'06' 


+CVDMIXD 


EQU 


X'07' 


+CVDMALC 


EQU 


X'08' 


+CVDMRLS 


EQU 


X'09' 


+CVDMMAP 


EQU 


X'OA' 


+CWOL 


EQU 


X'OB' 


+CWRFRD 


EQU 


X'OC 


+CWRFWR 


EQU 


X'OD' 


+CVSTAT 

+ 
+CVFL1 


DS 


XL1 


DS 


XL1 


+CV1IVT 


EQU 


X'80' 


+CV1I0AR 


EQU 


X'40' 


+CV 1 PGM 


EQU 


X'20' 


+CV1MRCDS 


EQU 


X'10' 


+CV1IRCDS 


EQU 


X'08' 


+CV1MAPIX 


EQU 


X'04' 


+CV1MAPVT 


EQU 


X'02' 


+CV1MAPVL 


EQU 


X'01 • 


+CVFL2 


DS 


XL1 


+CV2HIVIE 


EQU 


X'80' 


+CV2VRF 


EQU 


X'40' 


+CV2CNT 


EQU 


X'20' 


+CV2RCVR 


EQU 


X'10' 


+CV2SRCH 


EQU 


X'08' 


+CV2DSNLY 


EQU 


X'04' 


+CV2VER 


EQU 


X'02' 


+CV2NLEVL 


EQU 


X'01' 


+* 






+ 


DS 


H 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CWRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


♦-CVPL 



FUNCTION BYTE 

CVAFDIR ACCESS=READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST 

BELOW) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



+* VALUES OF CVSTAT 

+*(THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
END 
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Example 2: Using the CVAFDIR Macro with an Indexed VTOC 

This example uses the CVAFDIR macro to read one or more DSCBs on a 
VTOC. The UCB is supplied to the program in register 4 (labeled RUCB). The 
TTR of each DSCB read is to be returned to the caller. This program must be 
APF authorized. 

The address of a parameter Ust is supplied to the program in register 5 (labeled 
RLIST). The parameter list contains one or more 3-word entries. The format of 
each 3-word entry is mapped by the LISTMAP DSECT. The first word contains 
the address of the data set name of the DSCB to be read. The second word 
contains the address of the 96-byte buffer into which the DSCB is to be read. 
The third word contains the address of the 3-byte TTR of the DSCB read. 

The CVPL is generated by a list form of the CVAFDIR macro at label CVPL. 
The BUFLIST, IXRCDS, lOAREA, and BRANCH keywords are coded on the 
list form of the macro. IXRCDS=KEEP and IOAREA=sKEEP are coded to 
avoid overhead if two or more DSCBs are to be read. BRANCH=(YES,PGM) 
is coded in the list form of the CVAFDIR macro to cause the CVPL to have the 
CVIPGM bit set to one; this will indicate to CVAF that the caller is authorized 
by APF and not in supervisor state. The execute forms of the CVAFDIR macro 
then specify BRANCH= YES, and not BRANCH=(YES,PGM), because the 
CVIPGM bit is set in the list form of the macro. 

The CVAFDIR macro with ACCESS=RLSE is coded before the program exits 
in order to release the CVAF I/O area and the index records buffer list. 
BUFLIST=0 is coded because no user-supplied buffer list is to be released; 
BUFLIST was coded on the Ust form of the CVAFDIR macro and, therefore, is 
in the CVBUFL field of the CVPL. This field must be set to zero for the 
release. 

EXAMPLE2 CSECT 

STM 14,12,12(13) 

BALR 12,0 

USING *,12 

ST 13, SAVEAREA+4 

LA RWORK , SAVEAREA 

ST RWORK, 8 (,13) 

LR 13, RWORK 

* REGISTERS 

« 

RWORK EQU 3 WORK REGISTER 

RUCB EQU 4 UCB ADDRESS SUPPLIED BY CALLER 

RLIST EQU 5 ADDRESS OF PARAMETER LIST 

RDSN EQU 6 ADDRESS OF DATA SET NAME 

RTTR EQU 7 ADDRESS OF TTR 

REGIS EQU 15 RETURN CODE REGISTER 15 
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« 
* 

* 
* 

TOPLOOP 



READ DSCB OF DATA SET NAME SUPPLIED. RETURN TTR OF DSCB. 
UCB ADDRESS SUPPLIED IN RUCB. 
ADDRESS OF PARAMETER LIST IN RLIST. 

WORD 1 OF PARAMETER LIST = ADDRESS OF DATA SET NAME 
WORD 2 OF PARAMETER LIST = ADDRESS OF DSCB TO BE RETURNED 
WORD 3 OF PARAMETER LIST = ADDRESS OF TTR TO BE RETURNED 
WORDS 1-3 DUPLICATED WITH THE HIGH ORDER BIT OF 
WORD 3 SET TO ONE FOR LAST ENTRY. 

USING LI STMAP, RLIST ADDRESSABILITY TO PARMLIST 



EQU 

XC 

01 

MVI 

LA 

ST 

01 

MVI 



* LOOP FOR EACH DSCB 

BUFLIST(BFLHLN+BFLELN) ,BUFLIST ZERO BUFFER LIST 



BFLHFL,BFLHDSCB 

BFLHNOE , 1 

RWORK,LISTDSCB 

RWORK,BFLEBUF 

BFLEFL,BFLETTR 

BFLELTH,DSCBLTH 

RDSN,LISTDSN 



DSCBS TO BE READ WITH BUFFER LIST 

ONE BUFFER LIST ENTRY 

ADDRESS OF DSCB BUFFER 

PLACE IN BUFFER LIST 

TTR OF DSCB RETURNED BY CVAF 

DATA PORTION OF DSCB READ - DSN 

SUPPLIED IN CVPL 

ADDRESS OF DATA SET NAME 



CVAFDIR DSN=(RDSN) ,UCB=(RUCB) ,MF=(E,CVPL) ,BRANCH=YES 

LOAD PARAMETER REG 1 
STORE UCB PTR IN PARM LIST 
STORE DSN PTR IN PARM LIST 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVT CVAF TABLE 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 
ADDRESS OF TTR TO BE RETURNED 
MAP OF TTR 
ANY ERROR 
BRANCH IF NOT 

ZERO TTR INDICATING NO DSCB 
GET NEXT ENTRY 
DSCB READ 

RETURN TTR OF DSCB 
GET NEXT ENTRY 
IS IT LAST ENTRY IN LIST? 
GET NEXT ENTRY 
PROCESS NEXT LIST 

RELEASE CVAF OBTAINED AREAS » 

RELEASE lOAREA * 

RELEASE VIER BUFFER LIST ♦ 

NO USER BUFFER LIST SUPPLIED TO RLSE* 
BRANCH ENTER CVAF * 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 
RESET CVAF FLAGS OFF 
GET BUFLIST ADDRESS AND 
STORE BUFLIST PTR IN PARM LIST 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVT CVAF TABLE 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 



+ 


LA 


1 , CVPL 


+ 


ST 


RUCB , 1 2 ( , 1 ) 


+ 


ST 


RDSN,16(,1) 


+ 


L 


15,16 


+ 


L 


15,328(,15) 


+ 


L 


15,12(,15) 


+ 


L 


15,0(,15) 


+ 


BALR 


14,15 




L 


RTTR,LISTTTR 




USING TTRMAP,RTTR 




LTR 


REG15,REG15 




BZ 


NOERROR 




XC 


TTR, TTR 




B 


RELOOP 


NOERROR 


EQU 


* 




MVC 


TTR,BFLEARG 


RELOOP 


EQU 


* 




TM 


LASTLIST,LASTBIT 




LA 


RLIST, NEXTLIST 




BZ 


TOPLOOP 




CVAFDIR ACCESS=RLSE, 






IOAREA=NOKEEP , 






IXRCDS=NOKEEP, 






BUFLIST=0 , 






BRANCH=YES , 






MF=(E,CVPL) 


+ 


LA 


1 , CVPL 


+ 


MVI 


6(1) ,X'03' 


+ 


NI 


8(1) ,B'10110111' 


+ 


LA 


15,0 


+ 


ST 


15,20(,1) 


+ 


L 


15,16 


+ 


L 


15,328(,15) 


+ 


L 


15,12(,15) 


+ 


L 


15,0(,15) 


+ 


BALR 


14,15 




L 


1 3 , SAVEAREA+4 




RETURN (14,12) 
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LM 
BR 



14,12,12(13) 
14 



RESTORE THE REGISTERS 
RETURN 



BUFLIST ICVAFBFL DSECT=NO 



BUFFER LIST 



+* BUFFER LIST HEADER 



+BUFLIST DS 
+BFLHNOE DS 
+BFLHFL DS 
+ ORG 

+BFLHKEY DS 
+BFLHVIR EQU 
+BFLHDSCB EQU 
+ DS 

+BFLHSP DS 
+BFLHFCHN DS 
+♦ 
+BFLHLN EQU 



OF 

XL1 

XL1 

BFLHFL 

XL1 

X'08' 

X'04' 

XL1 

XL1 

A 



BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 



PROTECT KEY (FIRST 4 BITS) 
BUF. LIST ENTRIES DESCRIBE VIRS 
BUF. LIST ENTRIES DESCRIBE DSCBS 
RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 
FORWARD CHAIN PTR TO NEXT BUF. 
LIST 
♦-BUFLIST LENGTH OF BUFFER LIST HET^ER 

4- ««««***«««*» 4t 4e *************************** ***************************** * 

+* BUFFER LIST ENTRY 



+BFLE 


DS 


OF 


+BFLEFL 


DS 


XL1 


+BFLERBA 


EQU 


X'80' 


+BFLECHR 


EQU 


X'40' 


+BFLETTR 


EQU 


X'20' 


+BFLEAUPD 


EQU 


X'10' 


+BFLEMOD 


EQU 


X'08' 


+BFLESKIP 


EQU 


X'04' 


+BFLEIOER 


EQU 


X'02' 


+ 


DS 


XL1 


+BFLELTH 


DS 


XL1 


+♦ 






+BFLEARG 


DS 


XL5 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XLS 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL4 


+BFLEBUF 


DS 


A 


+BFLELN 


EQU 


♦-BFLE 


SAVEAREA 


DS 


18F 


LISTMAP 


DSECT 




LISTDSN 


DS 


F 


LISTDSCB 


DS 


F 



LISTTTR DS 



OF 



LASTLIST 


DS 


X 


LASTBIT 


EQU 


X'80' 




DS 


XL3 


NEXTLIST 


EQU 


* 


DSCB 


DSECT 






IECSDSL1 (1) 



BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

'TTR' OF ARGUMENT 

'RBA' OF ARGUMENT 
BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
REGISTER SAVE AREA 

ADDRESS OF DATA SET NAME 

ADDRESS OF BUFFER FOR DSCB TO BE 

RETURNED 

ADDRESS OF TTR OF DSCB TO BE 

RETURNED 

FIRST BYTE 

LAST ENTRY IN LIST 

REMAINDER OF TTR ADDRESS 

NEXT LIST 
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+IECSDSL1 


EQU 


* 


+IECSDSF1 


EQU 


lECSDSLI 


+DS1DSNAM 


DS 


CL44 


+DS1FMTID 


DS 


CL1 


+DS1DSSN 


DS 


CL6 


+DS1V0LSQ 


DS 


XL2 


+DS 1 CREDT 


DS 


XL3 


+DS1EXPDT 


DS 


XL3 


+DS 1 NOEPV 


DS 


XL1 


+DS1N0BDB 
+* 

+ 


DS 


XL1 


DS 


XL1 


+DS 1 SYSCD 


DS 


CL13 


+ 


DS 


XL7 


+DS1DS0RG 


DS 


XL2 


+» 




FIRST BYTE ( 


+DS1DSGIS 


EQU 


X'80' 


+* 






+DS1DSGPS 
J.* 


EQU 


X'40' 


+DS 1 DSGDA 


EQU 


X'20' 


+DS 1 DSGCX 


EQU 


X'10' 


+* 


EQU 


X'08' 


+* 


EQU 


X'04' 


+DS1DSGP0 


EQU 


X'02' 


+DS 1 DSGU 


EQU 


x'or 


+* 






+* 






+* 






+* 




SECOND BYTl 


+DS1DSGGS 


EQU 


X'80' 


+DS1DSGTX 


EQU 


X'40' 


+DS 1 DSGTQ 


EQU 


X'20' 


+* 


EQU 


X'10' 


+DS1ACBM 


EQU 


X'08' 


+DS 1 DSGTR 


EQU 


X'04' 


+* 


EQU 


X'02' 


+* 


EQU 


X'01 ' 


+DS1RECFM 


DS 


XL1 


+DS10PTCD 


DS 


XLl 


+DS 1 BLKL 


DS 


XL2 


+DS 1 LRECL 


DS 


XL2 


+DS 1 KEYL 


DS 


XLl 


+DS1RKP 


DS 


XL2 


+DS1DSIND 


DS 


XLl 


+DS 1 SCALO 


DS 


XL4 


+DS1LSTAR 


DS 


XL3 


+DS1TRBAL 


DS 


XL2 


+ 


DS 


XL2 


+DS1EXT1 


DS 


XL10 


+♦ 


FIRST 


BYTE 


+* 


SECOND BYTE 


+* 


THIRD 


- SIXTH BYTES 


+* 


SEVENTH - TENTH BYTES 


+DS1EXT2 


DS 


XL10 


+DS1EXT3 


DS 


XL10 


+DS1PTRDS 


DS 


XLS 


+DS 1 END 


EQU 


* 


DSCBLTH 


EQU 


♦-DSCB-L ' DS 1 DSNAM 


TTRMAP 


DSECT 




TTR 


DS 


XL3 



FORMAT 1 DSCB 

DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 

DATA SET ORGANIZATION 
DS1DS0RG 

IS - INDEXED SEQUENTIAL 
ORGANIZATION 

PS - PHYSICAL SEQUENTIAL 
ORGANIZATION 
DA - DIRECT ORGANIZATION 
CX - BTAM OR QTAM LINE GROUP 
RESERVED 
RESERVED 

PO - PARTITIONED ORGANIZATION 
U - UNMOVABLE, THE DATA 
CONTAINS LOCATION DEPENDENT 
INFORMATION 



aoiA 

a01A 

aoiA 
aoiA 
aoiA 
aoiA 
aoiA 
aoiA 



OF DS1DS0RG 
GS - GRAPHICS ORGANIZATION 301 A 
TX - TCAM LINE GROUP 301 A 

TQ - TCAM MESSAGE QUEUE aOlA 

RESERVED 301 A 

ACCESS METHOD CONTROL BLOCK 301 A 
TR - TCAM 3705 301 A 

RESERVED 301 A 

RESERVED 301 A 

RECORD FORMAT 
OPTION CODE 
BLOCK LENGTH 
RECORD LENGTH 
KEY LENGTH 

RELATIVE KEY POSITION 
DATA SET INDICATORS 
SECONDARY ALLOCATION 
LAST USED TRACK AND BLOCK ON TRACK 
BYTES REMAINING ON LAST TRACK USED 
RESERVED 

FIRST EXTENT DESCRIPTION 
EXTENT TYPE INDICATOR 
EXTENT SEQUENCE NUMBER 
LOWER LIMIT 
UPPER LIMIT 

SECOND EXTENT DESCRIPTION 
THIRD EXTENT DESCRIPTION 
POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 

LENGTH OF DATA PORTION OF DSCB 

TTR TO BE RETURNED 
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EXAMPLE2 CSECT 

CVPL CVAFDIR ACCESS=READ,BUFLIST=BUFLIST,MF=L, 

IOAREA=KEEP , 

IXRCDS=KEEP 



* 
KEEP lOAREA TO AVOID OVERHEAD * 
KEEP VIERS FOR 2ND AND SUBSEQUENT CALLS* 
CALLED IN PROGRAM STATE BUT APF * 
AUTHORIZED SO UCB IS SUPPLIED 



+ 


CNOP 


0,4 


+CVPL 


EQU 


* 


+ 


DC 


CL4 ' CVPL ' 


+ 


DC 


AL2(ICV8E-CVPL) 


+ 


DC 


XL1 '01 • 


+ 


DC 


XL1 '00' 


+ 


DC 


B'01001000' 


+ 


DC 


B'OOOOOOOO" 


+ 


DC 


H'O' 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(BUFLIST) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ICV8E 


EQU 


4c 




ORG 


CVPL 


CVPLMAP 


ICVAFPL DSECT=NO 


^.***»«««**4t**««:|c4e««)|c«*«««*««««« 


+ * 


CVAF 


PARAMETER LIST 


4.««*)|c*«**9|c**)|t««***««)|e***««*««»« 


+CVPLMAP 


DS 


OF 


+CVLBL 


DS 


CL4 


+CVLTH 


DS 


H 


+CVFCTN 


DS 


XL1 


+CVDIRD 


EQU 


X'01 ' 


+CVDIWR 


EQU 


X'02' 


+CVDIRLS 


EQU 


X'03' 


+CVSEQGT 


EQU 


X'04' 


+CVSEQGTE 


EQU 


X'05' 


+CVDMIXA 


EQU 


X'06' 


+CVDMIXD 


EQU 


X'07' 


+CVDMALC 


EQU 


X'08' 


+CVDMRLS 


EQU 


X'09' 


+CVDMMAP 


EQU 


X'OA' 


+CWOL 


EQU 


X'OB' 


+CWRFRD 


EQU 


X'OC 


+CWRFWR 


EQU 


X'OD' 


+CVSTAT 


DS 


XL1 


+ 







EBCDIC 'CVPL' 
LENGTH OF CVPL 
FUNCTION CODE 
STATUS INFORMATION 
FIRST FLAG BYTE 
SECOND FLAG BYTE 
RESERVED 
UCB ADDRESS 
DATA SET NAME ADDRESS 
BUFFER LIST ADDRESS 
INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 
DEB ADDRESS 
ARGUMENT ADDRESS 
SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 
NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 
COUNT AREA ADDRESS 
END OF CVPL 
OVERLAY CVPL WITH EXPANSION OF MAP 



CVAF PARAMETER LIST 

EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION BYTE 

CVAFDIR ACCESS=READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST * 

BELOW) 
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+CVFL1 


DS 


XL1 


+CV1IVT 


EQU 


X'80' 


+CV1I0AR 


EQU 


X'40' 


+CV1PGM 


EQU 


X'20' 


+CV1MRCDS 


EQU 


X'10' 


+CV1IRCDS 


EQU 


X'08' 


+CV1MAPIX 


EQU 


X'04' 


+CV1MAPVT 


EQU 


X'02' 


+CV1MAPVL 


EQU 


x'or 


+CVFL2 


DS 


XL1 


+CV2HIVIE 


EQU 


X'80' 


+CV2VRF 


EQU 


X'40' 


+CV2CNT 


EQU 


X'20' 


+CV2RCVR 


EQU 


X'10' 


+CV2SRCH 


EQU 


X'08' 


+CV2DSNLY 


EQU 


X'04' 


+CV2VER 


EQU 


X'02' 


+CV2NLEVL 


EQU 


x'or 


+* 






+ 


DS 


H 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CVVRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


♦-CVPLMAP 



FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



+* VALUES OF CVSTAT 

+*(THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
END 
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Example 3: Using the CVAFFILT Macro 



This example uses the CVAFFILT macro to read all format- 1, format-2, and 
format-3 DSCBS from a given VTOC, calculates the total number of DSCBs by 
format type, and returns the totals to the calling program (the caller of this 
example program, not the caller of CVAF). The address of a DEB opened to 
the VTOC is passed to the example program in register 1 (labeled Rl in the 
example). 

The buffer list and filter criteria list are defined in the program. The 
ICVAFBFL macro generates the buffer list, and the ICVFCL macro generates 
the filter criteria list. 



EXAMPLES CSECT 

* 

* INPUT . 

* 

* 

* PROCESS 

« 

* 

* 

-* • 

* OUTPUT 

* 
* 

* 

* THE CVAF PARAMETER LIST 



REGISTER 1 - ADDRESS OF A DEB OPENED TO THE VTOC. 
REGISTER 13 - ADDRESS OF A STANDARD REGISTER SAVE AREA 
REGISTER 14 - ADDRESS OF THE RETURN POINT WITHIN CALLER 

USE THE CVAFFILT MACRO (ACCESS=READ, ACCESS=RESUME, AND 
ACCESS=RLSE) TO READ ALL FORMAT 1,2, AND 3 DSCBS FROM A 
GIVEN VTOC. IF FILTER SERVICE DETECTS AN ERROR CONDITION, 
IT RETURNS DIAGNOSTIC INFORMATION FOR DEBUGGING T^ALYSIS. 

REGISTER 1 = ADDRESS OF THE DATA RETURN AREA (SEE LABEL 
RET$AREA AT THE END OF THIS LISTING) . 

REGISTER 15 = ZERO IF NO ERRORS WERE ENCOUNTERED. 

OTHERWISE, ERROR INFORMATION IS PROVIDED 

IN THE DATA RETURN AREA (SEE LABEL RET$ERR) . 



(CVPL) , FILTER CRITERIA LIST (FCL) , BUFFER 



* LIST, AND DSCB BUFFERS ARE DEFINED WITHIN THIS CSECT. 

* EQUATES FOR ASSEMBLY CONSTANTS AND REGISTERS 

NUMBER OF BUFFER LIST ELEMENTS AND BUFFERS DESIRED 



BFLE$N 


EQU 


11 


RO 


EQU 





Rl 


EQU 


1 


R2 


EQU 


2 


R3 


EQU 


3 


R4 


EQU 


4 


R5 


EQU 


5 


R11 


EQU 


11 


R12 


EQU 


12 


R13 


EQU 


13 


R14 


EQU 


14 


R15 


EQU 


15 



* 

*«***««4(«*«««4i*«4>4c*)|t*4e«***4t********«4i***4i«««*****4i**)t>4t ************** 

* SAVE CALLER'S REGISTERS AND ESTABLISH A NEW REGISTER SAVE AREA 

STM R14,R12,12(R13) SAVE CALLER'S REGISTERS 

BALR R12,0 ESTABLISH THIS PROGRAM'S 

USING *,R12 BASE REGISTER 

ST Rl3,SAVEAREA+4 SAVE ADDRESS OF CALLER'S SAVE AREA 

LA R15,SAVEAREA GET ADDRESS OF THE NEW SAVE AREA 

ST R15,8(,R13) CHAIN CALLER'S AREA TO OURS 

LR R13,R15 ESTABLISH THE NEW SAVE AREA 



»*«**««*«*«)|c*«***4i**»«»4>««*»«»*4c««4>**««***4t«)|c«*4t**«**««*««4t««*4t«*)|(*)|t 
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* ESTABLISH ADDRESSABILITY TO THE CVPL. PLACE GIVEN DEB ADDRESS 

* IN THE CVPL, INITIALIZE THE FLAG BYTE AND THE RETURN DATA AREA. 

LA R11,CVPL$DEF ESTABLISH ADDRESSABILITY 
USING CVPL$MAP,R11 TO THE CVPL 

ST R1,CVDEB PLACE GIVEN ADDR(DEB) IN CVPL 

MVI FLAGS, F$RSET RESET THE LOCAL FLAG BYTE 

XC RET$AREA,RET$AREA INIT. DATA RETURN AREA TO ZERO 
* 

* INITIALIZE THE BUFFER LIST HEADER (BFLH) AND ELEMENTS (BFLE) 

XC BFLH$DEF(BFL$SIZE) ,BFLH$DEF SET BUFR LIST AREA TO ZERO 

LA R1,BFLH$DEF R1 -> BUFFER LIST HEADER 

USING BFL$MAP,R1 ESTABLISH ADDRESSABILITY 

MVI BFLHNOE,BFLE$N SET NUMBER OF BUFFER ELEMENTS 

01 BFLHFL,BFLHDSCB IDENTIFY AS DSCB BUFR ELEMNT LIST 

LA R2,BFLH$DEF+BFLHLN R2 -> FIRST BUFFER LIST ELEMENT 

USING BFLE,R2 ESTABLISH ADDRESSABILITY 

LA R3,DSCB$DEF R3 -> FIRST DSCB BUFFER 

LA R4,BFLE$N R4 = NUMBER OF ELEMENTS AND BUFRS 

BFLE$INT 01 BFLEFL,BFLECHR REQUEST CCHHR ON RETURN 

MVI BFLELTH,DSCB$SIZ SET BUFR LNGTH TO FULL DSCB SIZE 

ST R3,BFLEBUF SET ADDR(DSCB BUFFER) 

LA R2,BFLELN(R2) R2 -> NEXT BUFFER LIST ELEMENT 

LA R3,DSCB$SIZ(R3) R3 -> NEXT DSCB BUFFER 

BCT R4,BFLE$INT LOOP THROUGH ALL ELEMENTS 

DROP R1,R2 DROP TEMP USING 

« 

* INITIALIZE THE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT 

XC FCL$DEF(FCL$SIZE) ,FCL$DEF SET FCL AREA TO ZERO 

LA R1,FCL$DEF R1 -> FCL HEADER 

USING FCL$MAP,R1 ESTABLISH ADDRESSABILITY 

MVC FCLID,FCL$ID SET THE EYECATCHER 'FCL ' 

MVC FCLCOUNT,=H' 1 ' SET NUMBER OF FCL ELEMENTS 

LA R2,FCLHDEND R2 -> FIRST (ONLY) FCL ELEMENT 

USING FCLDSN,R2 ESTABLISH ADDRESSABILITY 

MVI FCLDSNLG,X'02' SET LENGTH (DSN PATTERN) 

LA R3,=C'**' R3 -> C'**' 

ST R3,FCLDSNA SET ADDR{DSN PATTERN) 

DROP R1,R2 DROP TEMP USING 
* 

* ISSUE CVAFFILT ACCESS=READ REQUEST 

MVI RET$FTN,RET$READ IDENTIFY THE CURRENT FUNCTION 
CVAFFILT ACCESS=READ , FCL=FCL$DEF , BUFLIST=BFLH$DEF , 
MF=(E,CVPL$DEF) 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 
GET FCL ADDRESS AND 
STORE FCL PTR IN PARM LIST 
GET BUFLIST ADDRESS AND 
STORE BUFLIST PTR IN PARM LIST 
SVC 139 
♦ 

* TEST THE RETURN FROM CVAFFILT ACCESS=READ OR ACCESS=RESUME 

TEST$RET LTR R15,R15 IF DSCB RETURN IS COMPLETE 

BZ COUNTLST GO COUNT LAST SET OF DSCBS 

CH R15,=H'4' IF RETURN CODE OTHER THAN FOUR 

BNE ERR$RET GO RETURN THE ERROR CONDITION 

CLI CVSTAT,STAT064 IF OTHER THAN RESUME RECOMMENDED 



+ 


LA 


1 ,CVPL$DEF 


+ 


MVI 


6(1) ,X'OE' 


+ 


LA 


15,FCL$DEF 


+ 


ST 


15,16(,1) 


+ 


LA 


15,BFLH$DEF 


+ 


ST 


15,20(,1) 


+ 


SVC 


139 
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BNE 
B 



ERR$RET 
COUNTCUR 



GO RETURN THE ERROR CONDITION 
ELSE GO COUNT CURRENT DSCB SET 



* COUNT THE NUMBER OF FORMAT 1,2, AND 3 DSCBS RETURNED 



COUNTLST 01 FLAGS, F$LAST 
COUNTCUR LM R1,R3,RET$F1 

LA R4,FCL$DEF 

USING FCL$MAP,R4 

SLR R5 , R5 

ICM R5,B'00ir ,FCLDSCBR 

BZ TST$RSUM 

LA R4,DSCB$DEF 

USING DSCB$MAP,R4 
COUNTNXT CLI DS 1 FMTID , X ' F 1 ' 





BE 


C0UNT$F1 




CLI 


DS1FMTID,X'F2' 




BE 


C0UNT$F2 




LA 


R3,1 (R3) 


)|C 


B 


COUNTTST 


C0UNT$F2 


LA 


R2,1 (R2) 


41 


B 


COUNTTST 


C0UNT$F1 


LA 


R1,1 (R1) 


COUNTTST 


LA 


R4,DSCB$SIZ(R4) 




BCT 


R5 , COUNTNXT 




STM 


R1 ,R3,RET$F1 




DROP 


R4 



INDICATE LAST SET OF DSCBS 
GET PRIOR DSCB COUNTS 
R4 -> FCL HEADER 
ESTABLISH ADDRESSABILITY 
R5 = ZERO FOR FOLLOWING ICM 
R5 = NUMBER OF DSCBS RETURNED 
IF ZERO, GO TEST FOR RESUME 
R4 -> FIRST DSCB BUFFER 
ESTABLISH ADDRESSABILITY 
IF FORMAT 1 DSCB 

GO INCREMENT ITS COUNTER 
IF FORMAT 2 DSCB 

GO INCREMENT ITS COUNTER 
ELSE INCREMENT FORMAT 3 DSCB COUNT 
GO TEST FOR MORE DSCBS 

INCREMENT COUNT OF FORMAT 2 DSCBS 
GO TEST FOR MORE DSCBS 

INCREMENT COUNT OF FORMAT 1 DSCBS 
R4 -> NEXT DSCB BUFFER 
LOOP THROUGH ALL RETURNED DSCBS 
SAVE UPDATED DSCB COUNTS 
FINISHED COUNTING CURR DSCB SET 



* CONDITIONALLY ISSUE CVAFFILT ACCESS=RESUME REQUEST 

TST$RSUM TM FLAGS, F$LAST IF LAST SET OF DSCBS COUNTED 

BO RLSE$REQ GO REQUEST A RELEASE 

MVI RET$FTN,RET$RSUM IDENTIFY THE CURRENT FUNCTION 
CVAFFILT ACCESS=RESUME,MF=(E,CVPL$DEF) RESUME REQUEST 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 

GO TEST THE RETURN CODES 



+ 


LA 


1 , CVPL$DEF 


+ 


MVI 


6(1),X'0F' 


+ 


SVC 


139 




B 


TEST$RET 



* ISSUE CVAFFILT ACCESS=RLSE REQUEST 

RLSE$REQ MVI RET$FTN,RET$RLSE IDENTIFY THE CURRENT FUNCTION 
CVAFFILT ACCESS=RLSE , FLC=0 , BUFLIST=0 , FLTAREA=NOKEEP , 
MF=(E,CVPL$DEF) 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 
RESET CVAF FLAGS OFF 
GET FCL ADDRESS AND 

STORE FCL PTR IN PARM LIST 
GET BUFLIST ADDRESS AND 

STORE BUFLIST PTR IN PARM LIST 

IF NO ERROR ON RELEASE REQUEST 

GO RETURN TO CALLER 
ELSE INDICATE ERROR IN RELEASE 



+ 


LA 


1,CVPL$DEF 


+ 


MVI 


6(1) ,X'10' 


+ 


NI 


10(1) ,B'01111111' 


+ 


LA 


15,0 


+ 


ST 


15,16(,1) 


+ 


LA 


15,0 


+ 


ST 


15,20(,1) 


+ 


SVC 


139 




LTR 


R15,R15 




BZ 


RETURN 




LA 


R1,RET$RLSE 



4t«i|c4i«*«4e4i«4t4t)|i«*«**4i4t«)|t«4c«a|c4i4t)|c)|i4i««4t4t4i4i4i4i«4i4t4t«*«4i4i*«««4i4t)|t*4i4i4t«4i4t4i««4(4i4i 

♦ PLACE ERROR INFORMATION IN THE OUTPUT DATA RETURN AREA 

ERR$RET MVC RET$STAT,CVSTAT COPY CVSTAT TO RETURN AREA 
ST R15,RET$RC COPY CVAFFILT 'S RETURN CODE 
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* ASSUME R15 = DESIRED RETURN 

* RESTORE CALLER'S REGISTERS 



RETURN 


LA 


R1,RET$AREA 




L 


Rl3,SAVEAREA+4 




L 


R14,12{R13) 




L 


R0,20(R13) 




LM 


R2,R12,28(R13) 




BR 


R14 


FLAGS 


DC 


X'OO' 


F$RSET 


EQU 


X'OO' 


F$LAST 

* 


EQU 
LTORG 


X'80' 

=H'1 ' 

=C'**' 

=H'4' 



CODE, SET R1 -> DATA RETURN AREA, 
0, 2-14, AND RETURN TO CALLER 

R1 -> OUTPUT DATA RETURN AREA 
R13 -> CALLER'S REG SAVE AREA 
RESTORE CALLER'S REGISTER 14 
RESTORE CALLER'S REGISTER 
RESTORE CALLER'S REGISTERS 2-12 
RETURN TO CALLER 
LOCAL FLAG BYTE 
FLAG RESET VALUE 
LAST DSCB SET ENCOUNTERED 



SAVEAREA DC ISF'O' 

* 

* MAPPING MACROS 

CVPL$MAP ICVAFPL CVPLFSA=YES 
+* CVAF PARAMETER LIST 
+CVPL$MAP DSECT 



+ 


DS 


OF 


+CVLBL 


DS 


CL4 : 


+CVLTH 


DS 


H 


+CVFCTN 


DS 


XL1 


+CVDIRD 


EQU 


X'01' 


+CVDIWR 


EQU 


X'02' 


+CVDIRLS 


EQU 


X'03' 


+CVSEQGT 


EQU 


X'04' 


+CVSEQGTE 


EQU 


X'05' 


+CVDMIXA 


EQU 


X'06' 


+CVDMIXD 


EQU 


X'07' 


+CVDMALC 


EQU 


X'08' 


+CVDMRLS 


EQU 


X'09' 


+CVDMMAP 


EQU 


X'OA' 


+CWOL 


EQU 


X'OB' 


+CWRFRD 


EQU 


X'OC 


+CWRFWR 


EQU 


X'OD' 


+CVFIRD 


EQU 


X'OE' 


+CVFIRES 


EQU 


X'OF' 


+CVFIRLS 


EQU 


X'10' 


+CVSTAT 

+ 

+CVFL1 


DS 


XL1 


DS 


XL1 


+CV1IVT 


EQU 


X'80' 


+CV1I0AR 


EQU 


X'40' 


+CV1PGM 


EQU 


X'20' 


+CV1MRCDS 


EQU 


X'10' 


+CV1IRCDS 


EQU 


X'08' 


+CV1MAPIX 


EQU 


X'04' 


+CV1MAPVT 


EQU 


X'02' 


+CV1MAPVL 


EQU 


X'01' 


+CVFL2 


DS 


XL1 


+CV2HIVIE 


EQU 


X'80' 


+CV2VRF 


EQU 


X'40' 


+CV2CNT 


EQU 


X'20' 


+CV2RCVR 


EQU 


X'10' 



REGISTER SAVE AREA 

CVAF PARAMETER LIST 

EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION BYTE 

CVAFDIR ACCESS=READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

CVAFFILT ACCESS=READ 

CVAFFILT ACCESS=RESUME 

CVAFFILT ACCESS=RLSE 

STATUS INFORMATION (SEE LIST 

BELOW) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 
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+CV2SRCH 


EQU 


X'08' 


+CV2DSNLY 


EQU 


X'04' 


+CV2VER 


EQU 


X'02' 


+CV2NLEVL 


EQU 


X'01 ' 


+♦ 






+CVFL3 


DS 


XL1 


+CV3FILT 


EQU 


X'80' 


+CV3IXERR 


EQU 


X'40' 


+ 


DS 


XL1 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+ 


ORG 


CVDSN 


+CVFCL 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CWRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVFSA 


DS 


A 


+CVPLNGTH 


EQU 


*-CVPL$MAP 



SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

THIRD FLAG BYTE 

FLTAREA=KEEP 

INDEX ERROR FOUND 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

FILTER CRITERIA LIST ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 

FILTER SAVE AREA ADDRESS 



+* VALUES OF CVSTAT 

+*(THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 



FCL$MAP 


ICVFCL 


+ «**4i«*****««««««**)|c*««*4<*«4t***#** 


+ * 


FILTER CRITERIA LIST 


4.*4citE4t«*)ti)tc4c**gtc4i]|t](e4E4c)|i*4c********«]|c*«itt 


+FCL$MAP 


DSECT 




+FCLID 


DS 


CL4 


+FCLCOUNT 


DS 


H 


+FCLDSCBR 


DS 


H 


+FCL1FLAG 


DS 


X 


+FCL1LIST 


EQU 


X'80' 


+* 






+FCL10RDR 


EQU 


X'40' 


+FCL2FLAG 


DS 


X 


+FCL2SEQ 


EQU 


X'80' 


+FCL2SDIR 


EQU 


X'40' 


+* 






+FCLDRSV 


DS 


XL6 


+FCLHDEND 


EQU 


* 


+FCLHDLEN 


EQU 


*-FCLID 


+* 






+ 


DSECT 




+FCLDSN 


CL8 




+ 


ORG 


FCLDSN 


+FCLDSNST 


DS 


X 


+FCLSTOO 


EQU 


X'OO' 


+FCLST01 


EQU 


X'01 ' 


+* FOR FCLST02 


THROUGH FCLST05 — 


+* DSCB(S; 


I FOR 


THE ASSOCIATED DSN 


+FCLST02 


EQU 


X'02' 


+FCLST03 


EQU 


X'03' 


+FCLST04 


EQU 


X'04' 


+FCLST05 


EQU 


X'05' 


+* 






+* 






+* 






+FCLDSNLG 


DS 


X 



CVAF FILTER CRITERIA LIST 

EYE CATCHER ' FCL ' 

NUMBER OF DSN ' S IN LIST 

NUMBER OF DSCB ' S RETURNED 

REQUEST FLAG BYTE 

LIST CONTAINS FULLY QUALIFIED 

DATA SET NAMES 

CALLER REQUESTS FCL ORDER 

STATUS FLAG BYTE 

SEQUENTIAL VTOC ACCESS SELECTED 

SEQUENTIAL VTOC ACCESS REQUIRED 

AT LEAST ONE DIRECT DSCB READ 
RESERVED 

DSN ENTRIES DIRECTLY FOLLOW 
LENGTH OF FCL HEADER 

MAP OF EACH DSN ELEMENT 
DATA SET NAME INFORMATION 

STATUS OF THIS DATA SET NAME 
DSN REMAINS TO BE PROCESSED 
DSCB(S) HAVE BEEN RETURNED 
CVAFFILT WILL NOT RETURN ANY 



DSN NOT FOUND 
ANOMALY FOUND IN DSCB(S) 
ANOMALY FOUND IN CVAFFILT 
NUMBER OF DSCBS FOR THIS DSN 
IS GREATER THAN THE TOTAL 
NUMBER OF BFLE PROVIDED 

DATA SET NAME LENGTH 
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+FCL3FLAG 


DS 


X 


+FCL3UPDT 


EQU 


X'80' 


+ * 






+FCLDSNRV 


DS 


X 


+FCLDSNA 


DS 


F 


+FCLDSNEL 


EQU 


*-FCLDSN 



FLAG BYTE 

THIS ELEMENT WAS PROCESSED 

BY THIS INVOCATION 
RESERVED 

DATA SET NAME ADDRESS 
LENGTH OF DSN INFO ENTRY 



BFL$MAP ICVAFBFL 
+♦ BUFFER LIST HEADER 
+BFL$MAP DSECT 



BUFFER LIST HEADER 



+ 


DS 


OF 


+BFLHNOE 


DS 


XL1 


+BFLHFL 


DS 


XL1 


+ 


ORG 


BFLHFL 


+BFLHKEY 


DS 


XL1 


+BFLHVIR 


EQU 


X'08' 


+BFLHDSCB 


EQU 


X'04' 


+ 


DS 


XL1 


+BFLHSP 


DS 


XL! 


+BFLHFCHN 


DS 


A 


+♦ 






+BFLHLN 


EQU 


*-BFL$MAP 



+* BUFFER LIST ENTRY 



+BFLE 


DSECT 




+ 


DS 


OF 


+BFLEFL 


DS 


XL1 


+BFLERBA 


EQU 


X'80' 


+BFLECHR 


EQU 


X'40' 


+BFLETTR 


EQU 


X'20' 


+BFLEAUPD 


EQU 


X'10' 


+BFLEMOD 


EQU 


X'08' 


+BFLESKIP 


EQU 


X'04' 


+BFLEIOER 


EQU 


X'02' 


+ 


DS 


XL1 


+BFLELTH 


DS 


XL1 


+* 






+BFLEARG 


DS 


XLS 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XL3 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL4 


+BFLEBUF 


DS 


A 


+BFLELN 


EQU 


♦-BFLE 



NUMBER OF ENTRIES 
KEY AND FLAG BYTE 

PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 

BUF. LIST ENTRIES DESCRIBE DSCBS 

RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 

FORWARD CHAIN PTR TO NEXT BUF. 

LIST 

LENGTH OF BUFFER LIST HEADER 

BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

'TTR' OF ARGUMENT 

•RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 



PUSH PRINT 

PRINT NOGEN 
DSCB$MAP DSECT 

IECSDSL1 (1) USE FORMAT 1 DSCB MAPPING TO GET BUFFER SIZE 
DSCB$SIZ EQU *-IECSDSLl LENGTH OF FULL DSCB 

POP PRINT 



* SPACE ALLOCATION FOR CVPL, FCL, BFL, AND DSCB BUFFERS 

EXAMPLES CSECT , CONTINUATION OF CSECT 

CVPL$DEF CVAFFILT MF=L , BRANCH=NO , FLTAREA=KEEP 
+ CNOP 0,4 

+CVPL$DEF EQU 
+ DC 

+ DC 

+ DC 

+ DC 



CL4 • CVPL ' 

AL2 (ICV1 1E-CVPL$DEF) 

XL1 'OE' 

XL1 '00' 



EBCDIC 'CVPL' 
LENGTH OF CVPL 
FUNCTION CODE 
STATUS INFORMATION 
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+ 


DC 


B' 00000000' 


+ 


DC 


B'OOOOOOOO' 


+ 


DC 


B' 10000000' 


+ 


DC 


X'O' 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A{0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ICV11E 


EQU 


* 



FIRST FLAG BYTE 

SECOND FLAG BYTE 

THIRD FLAG BYTE 

RESERVED 

UCB ADDRESS 

FILTER CRITERIA LIST ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDRESS 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 

FILTER SAVE AREA ADDRESS 

END OF CVPL 



FCL HEADER AND ONE FCL ELEMENT 



FCL$ID DC CL4'FCL ' 

FCL$DEF DS (FCLHDLEN+FCLDSNEL) X 

FCL$SIZE EQU ♦-FCL$DEF 

* DEFINE A CVAF BUFFER LIST WITH N BUFFER LIST ELEMENTS 
BFLH$DEF DS (BFLHLN)X BUFFER LIST HEADER 
BFLE$DEF DS (BFLE$N*BFLELN) X N BUFFER LIST ELEMENTS 
BFL$SIZE EQU *-BFLH$DEF 

♦ DEFINE N FULL DSCB BUFFERS 
DSCB$DEF DS (BFLE$N*DSCB$SIZ) X 



* OUTPUT DATA RETURN AREA 

DS OF 

OUTPUT DATA RETURN AREA 

COUNT OF FORMAT 1 DSCBS RETURNED BY CVAFFILT 
COUNT OF FORMAT 2 DSCBS RETURNED BY CVAFFILT 
COUNT OF FORMAT 3 DSCBS RETURNED BY CVAFFILT 

IF NO ERROR CONDITION WAS ENCOUNTERED THEN 

REGISTER 15 = ZERO ON RETURN 
OTHERWISE THE FOLLOWING INFORMATION IS PROVIDED 
IDENTIFICATION OF CVAFFILT SUBFUNCTION 
CVAFFILT ACCESS=READ 
CVAFFILT ACCESS=RESUME 
CVAFFILT ACCESS=RLSE 
UNUSED 

COPY OF CVSTAT FROM CVAFFILT 
COPY OF THE RETURN CODE FROM CVAFFILT 



RET$AREA 


DS 


0XL20 


RET$F1 


DC 


F'O' 


RET$F2 


DC 


F'O' 


RET$F3 

4t 


DC 


F'O' 


RET$ERR 

* 


DS 


0XL8 


* 
RET$FTN 


DC 


X'OO' 


RET$READ 


EQU 


X'01 • 


RET$RSUM 


EQU 


X'02' 


RET$RLSE 


EQU 


X'03' 




DC 


XL2 ' 00 ' 


RET$STAT 


DC 


X'OO' 


RET$RC 


DC 


F'O' 



END 



Example 4: Using the CVAFSEQ Macro with an Indexed VTOC 



This example uses the CVAFSEQ macro to coum the number of ISAM data sets 
whose data set names are within the range defined by two supplied data set 
names. The addresses of the two data set names are supplied to the program in 
registers 6 and 7, labeled RDSNl and RDSN2, respectively. The address of a 
DEB open to the VTOC is supplied in register 4, labeled RDEB. 
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The CVAF parameter list is expanded by a list form of the CVAFSEQ macro. 
ACCESSssGTEQ is specified on the list form of the macro and is, therefore, not 
coded in the first execution of the CVPL. Subsequent executions of the CVPL 
(at label RELOOP) specify ACCESS^GT. 

End of data is tested by comparing the CVSTAT field to the value of STAT032, 
which is an equate in the ICVAFPL mapping macro. 

The count of ISAM DSCBs matching the data set name criterion is returned in 
register 15, unless an error is encountered, in which case a negative 1 is returned 
in register IS. 
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EXAMPLE4 CSECT 

STM 14,12,12(13) 

BALR 12,0 

USING *,12 

ST 13, SAVEAREA+4 

LA RWORK , SAVEAREA 

ST RWORK, 8 (,13) 

LR 13, RWORK 

* REGISTERS 

REG1 EQU 1 REGISTER 1 

RWORK EQU 3 WORK REGISTER 

RDEB EQU 4 DEB ADDRESS 

RDSN1 EQU 6 ADDRESS OF DATA SET NAME 1 

RDSN2 EQU 7 ADDRESS OF DATA SET NAME 2 

REGIS EQU 15 RETURN CODE REGISTER 15 

* 

» COUNT THE NUMBER OF ISAM DATA SETS WHOSE DATA SET NAMES ARE 

* BETWEEN DSN1 AND DSN2 INCLUSIVELY. 

♦ RDSN1 CONTAINS ADDRESS OF DSNI . 

* RDSN2 CONTAINS ADDRESS OF DSN2 . 

♦ ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB. 

♦ . 

XC BUFLIST(BFLHLN+BFLELN) ,BUFLIST ZERO BUFFER LIST 

01 BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 

MVI BFLHN0E,1 ONE BUFFER LIST ENTRY 

LA RWORK, DS1FMTID ADDRESS OF DSCB BUFFER 

ST RWORK, BFLEBUF PLACE IN BUFFER LIST 

MVI BFLELTH,DSCBLTH DATA PORTION OF DSCB READ - DSN * 

SUPPLIED IN CVPL 
MVC DS1DSNAM,0(RDSN1) MOVE IN STARTING DATA SET NAME TO * 

WORKAREA 
XR RWORK, RWORK ZERO COUNT 

CVAFSEQ DEB=(RDEB), FIND FIRST DATA SET WHOSE DATA SET ♦ 
BUFLIST=BUFLIST, NAME IS GREATER THAN OR EQUAL TO ♦ 
MF=(E,CVPL) THAT OF DSNI 

+ LA 1,CVPL LOAD PARAMETER REG 1 

+ ST RDEB, 36 (,1) STORE DEB PTR IN PT^RM LIST 

+ SVC 139 
LOOP EQU ♦ LOOP UNTIL END OF DATA OR DATA SET * 

NAME GREATER THAN DSN2 
USING CVPL, REG 1 ADDRESSABILITY TO CVPL 

LTR REG15,REG15 ANY ERROR 

BZ TESTDSN BRANCH IF NOT-CHECK DSN LIMIT 

* 

• DETERMINE WHAT ERROR IS 

« 

C REG15,ERROR4 IS RETURN CODE 4 

BNE OTHERERR BRANCH IF NOT 4 

CLI CVSTAT,STAT032 IS IT END OF DATA? 

BNE OTHERERR BRANCH IF NOT 

DROP REG1 ADDRESSABILITY TO CVPL NOT NEEDED 

« 

♦ END OF DATA 

« 
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B 


RELEASE 


TESTDSN 


EQU 


* 




CLI 


DS1FMTID,C' 1 • 




BNE 


CKLAST 




CLC 


DS1DSNAM,0(RDSN2) 




BNH 


TESTIS 




B 


RELEASE 


TESTIS 


EQU 


♦ 




TM 


DS1DS0RG,DS1DSGIS 




BZ 


CKLAST 




LA 


RW0RK,1 (,RWORK) 


CKLAST 


EQU 


* 




CLC 


DS1DSNAM,0(RDSN2) 




BNH 


RELOOP 




B 


RELEASE 


RELOOP 


EQU 


« 




CVAFSEQ ACCESS=GT , MF= ( 


+ 


LA 


1 , CVPL 


+ 


MVI 


6(1) ,X'04' 


+ 


SVC 


139 




B 


LOOP 


OTHERERR 


EQU 


* 


* 
* 

iff 


*««4t««***4i**«*****««««« 


UNEXPECTED ERROR PROCE 


m*******^**m********ittm**m****** 




LA 


RW0RK,1 (0,0) 




LNR 


RWORK,RWORK 


RELEASE 


CVAFDIR ACCESS=RLSE, 






BUFLIST=0, 






IXRCDS=NOKEEP, 






MF=(E,CVPL) 


+RELEASE 


EQU 


* 


+ 


LA 


1 , CVPL 


+ 


MVI 


6(1) ,X'03' 


+ 


NI 


8(1) ,B'11110111' 


+ 


LA 


15,0 


+ 


ST 


15,20(,1) 


+ 


SVC 


139 




LR 


REG15,RW0RK 




L 


13,SAVEAREA+4 




RETURN (14,12) ,RC=(15) 


+ 


L 


14,12(13,0) 


+ 


LM 


0,12,20(13) 


+ 


BR 


14 


ERR0R4 


DC 


F'4' 


BUFLIST 


ICVAFBFL DSECT=NO 



RELEASE CVAF RESOURCES AND RETURN 
IS DATA SET NAME GREATER THAN DSN2 
IS THIS A FORMAT 1 DSCB? 
BRANCH IF NO. CAN NOT BE ISAM. 
HAS LIMIT BEEN REACHED? 
BRANCH IF NO-TEST FOR ISAM 
RELEASE CVAF RESOURCES AND RETURN 
ONLY COUNT ISAM 
IS DATA SET ISAM 
BRANCH IF NO-DO NOT COUNT IT 
INCREMENT COUNT BY ONE 
CHECK IF LAST DATA SET NAME (DSN2) 
HAS LIMIT BEEN REACHED? 
BRANCH IF NO-READ NEXT ONE 
RELEASE CVAF RESOURCES AND RETURN 
READ NEXT DSCB 
E,CVPL) GET DSCB WITH DATA SET NAME 
GREATER THAN THE ONE LAST READ 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 

CHECK RESULTS OF CVAFSEQ 
UNEXPECTED ERROR 



ONE IN RWORK 

SET NEGATIVE COUNT INDICATING ERROR 
RELEASE CVAF BUFFERS/IOAREA * 

DO NOT RELEASE USER BUFFER LIST * 
RELEASE CVAF VIER BUFFERS * 

RELEASE CVAF I/O AREA 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 
RESET CVAF FLAGS OFF 
GET BUFLIST ADDRESS AND 
STORE BUFLIST PTR IN PARM LIST 

CURRENT COUNT IS RETURN CODE 

RETURN CURRENT COUNT 

RESTORE REGISTER 14 
RESTORE THE REGISTERS 
RETURN 

ERROR RETURN CODE 4 

BUFFER LIST 
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+* BUFFER LIST HEADER 



+BUFLIST DS OF 

+BFLHNOE DS XLI 

+BFLHFL DS XLI 

+ ORG BFLHFL 

+BFLHKEY DS XLI 

+BFLHVIR EQU X ' 08 ' 

+BFLHDSCB EQU X'04' 

+ DS XLI 

+BFLHSP DS XLI 

+BFLHFCHN DS A 
+ * 

+BFLHLN EQU *-BUFLIST 



BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 

PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 

BUF. LIST ENTRIES DESCRIBE DSCBS 

RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 

FORWARD CHAIN PTR TO NEXT BUF. 

LIST 

LENGTH OF BUFFER LIST HEADER 



+* BUFFER LIST ENTRY 

4.4e4c4<4c4'4c4c4c4c4c4c4c4c4c4E4c4c4c4i4c4c*4c4c4c4c4c4c4c4c«4c4c4c4c4e4c4c4c4c4c4<4c4c4c4i4c4c4>4c4c4c4c4c4c4c4c4c4t4c4c4c4c4c4<4i4c4c4c4c4i 



+BFLE 


DS 


OF 


+BFLEFL 


DS 


XLI 


+BFLERBA 


EQU 


X'80' 


+BFLECHR 


EQU 


X'40' 


+BFLETTR 


EQU 


X'20' 


+BFLEAUPD 


EQU 


X'lO' 


+BFLEMOD 


EQU 


X'08' 


+BFLESKIP 


EQU 


X'04' 


+BFLEIOER 


EQU 


X'02' 


+ 


DS 


XLI 


+BFLELTH 


DS 


XLI 


+* 






+BFLEARG 


DS 


XL5 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XLS 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL4 


+BFLEBUF 


DS 


A 


+BFLELN 


EQU 


*-BFLE 




IECSDSL1 (1) 


+IECSDSL1 


EQU 


4c 


+IECSDSF1 


EQU 


IECSDSL1 


+DS 1 DSNAM 


DS 


CL44 


+DS1FMTID 


DS 


CL1 


+DS1DSSN 


DS 


CL6 


+DS1V0LSQ 


DS 


XL2 


+DS 1 CREDT 


DS 


XL3 


+DS 1 EXPDT 


DS 


XLS 


+DS 1 NOEPV 


DS 


XLI 


+DS1N0BDB 


DS 


XLI 


+ * 






+ 


DS 


XLI 


+DS1SYSCD 


DS 


CL13 


+ 


DS 


XL7 


+DS1DS0RG 


DS 


XL2 



BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

'TTR' OF ARGUMENT 

•RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
FORMAT 1 DSCB DATA SET NAME AND 
BUFFER 
FORMAT 1 DSCB 

DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 
DATA SET ORGANIZATION 
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+* 




FIRST BYTE 01 


I" DS1DS0RG 




+DS1DSGIS 


EQU 


X'80' 


IS - INDEXED SEQUENTIAL 


aoiA 


+* 






ORGANIZATION 




+DS1DSGPS 


EQU 


X'40' 


PS - PHYSICAL SEQUENTIAL 


aoiA 


+* 






ORGANIZATION 




+DS 1 DSGDA 


EQU 


X'20' 


DA - DIRECT ORGANIZATION 


aoiA 


+DS1DSGCX 


EQU 


X'10' 


CX - BTAM OR QTAM LINE GROUP 


aoiA 


+» 


EQU 


X'08' 


RESERVED 


aoiA 


+* 


EQU 


X'04' 


RESERVED 


aoiA 


+DS1DSGP0 


EQU 


X'02' 


PO - PARTITIONED ORGANIZATION 


aoiA 


+DS1DSGU 


EQU 


X'01 • 


U - UNMOVABLE, THE DATA 


aoiA 


+* 






CONTAINS LOCATION DEPENDENT 




+* 
+* 
+* 






INFORMATION 






SECOND BYTE 


OF DS1DS0RG 




+DS1DSGGS 


EQU 


X'80' 


GS - GRAPHICS ORGANIZATION 


aoiA 


+DS 1 DSGTX 


EQU 


X'40' 


TX - TCAM LINE GROUP 


aoiA 


+DS 1 DSGTQ 


EQU 


X'20' 


TQ - TCAM MESSAGE QUEUE 


aoiA 


+ * ', 


EQU 


X'10' 


RESERVED 


aoiA 


+DStACBM 


EQU 


X'08' 


ACCESS METHOD CONTROL BLOCK 


aoiA 


+DS1DSGTR 


EQU 


X'04' 


TR - TCAM 3705 


aoiA 


+* 


EQU 


X'02' 


RESERVED 


aoiA 


+* 


EQU 


X'01 ' 


RESERVED 


aoiA 


+DS 1 RECFM 


DS 


XL1 


RECORD FORMAT 




+DS10PTCD 


DS 


XL1 


OPTION CODE 




+DS 1 BLKL 


DS 


XL2 


BLOCK LENGTH 




+DS 1 LRECL 


DS 


XL2 


RECORD LENGTH 




+DS1KEYL 


DS 


XL1 


KEY LENGTH 




+DS 1 RKP 


DS 


XL2 


RELATIVE KEY POSITION 




+DS1DSIND 


DS 


XL1 


DATA SET INDICATORS 




+DS 1 SCALO 


DS 


XL4 


SECONDARY ALLOCATION 




+DS 1 LSTAR 


DS 


XL3 


LAST USED TRACK AND BLOCK ON TRACK 


+DS 1 TRBAL 


DS 


XL2 


BYTES REMAINING ON LAST TRACK 


USED 


+ 


DS 


XL2 


RESERVED 




+DS1EXT1 


DS 


XL10 


FIRST EXTENT DESCRIPTION 




+* 


FIRST 


BYTE 


EXTENT TYPE INDICATOR 




+* 


SECOND BYTE 


EXTENT SEQUENCE NUMBER 




+ * 


THIRD 


- SIXTH BYTES 


LOWER LIMIT 




+ * 


SEVENTH - TENTH BYTES 


UPPER LIMIT 




+DS1EXT2 


DS 


XL10 


SECOND EXTENT DESCRIPTION 




+DS1EXT3 


DS 


XL10 


THIRD EXTENT DESCRIPTION 




+DS 1 PTRDS 


DS 


XLS 


POSSIBLE PTR TO A FORMAT 2 OR 


3 DSCB 


+DS 1 END 


EQU 


* 






DSCBLTH 


EQU 


♦-lECSDSLl-L'DSIDSNAM LENGTH OF DATA PORTION OF DSCB 


SAVEAREA 


DS 


18F 


SAVE AREA 




CVPL 


CVAFSEQ ACCESS=GTEQ, 


READ DSCB WITH DSN >= SUPPLIED DSN 






IXRCDS=KEEP, 


KEEP VIERS IN STORAGE DURING CALLS 






DSN=DS1DSNAM, 


SUPPLIED DATA SET NAME 








BUFLIST=BUFLIST, 










MF=L 






+ 


CNOP 


0,4 






+CVPL 


EQU 


* 






+ 


DC 


CL4 ' CVPL • 


EBCDIC 'CVPL' 




+ 


DC 


AL2{ICV10E-CVPL) 


LENGTH OF CVPL 




+ 


DC 


XLI'05' 


FUNCTION CODE 




+ 


DC 


XLI'OO' 


STATUS INFORMATION 




+ 


DC 


B'00001000' 


FIRST FLAG BYTE 




+ 


DC 


B'OOOOOOOb' 


SECOND FLAG BYTE 
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+ DC H ' • 

+ DC A{0) 

+ DC A(DSIDSNAM) 

+ DC A(0) 

+ DC A(0) 

+ DC A(0) 

+ DC A(0) 

+ DC A(0) 

+ DC A(0) 

+ DC A(0) 

+ DC A(0) 

+ DC A(0) 

+ DC A{0) 

+ DC A{0) 

+ICV10E EQU * 

ORG CVPL 

CVPLMAP ICVAFPL DSECT=NO 

+* CVAF PARAMETER LIST 



RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VI XM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 
EXPAND MAP OVER LIST 
CVPL MAP 



DS 

DS 

DS 

DS 

EQU 

EQU 



+CVPLMAP 
+CVLBL 
+CVLTH 
+CVFCTN 
+CVDIRD 
+CVDiWR 
+CVDIRLS EQU 
+CVSEQGT EQU 
+CVSEQGTE EQU 
+CVDMIXA EQU 
+CVDMIXD EQU 
+CVDMALC EQU 
+CVDMRLS EQU 
+CVDMMAP EQU 
+CWOL EQU 
+CWRFRD EQU 
+CWRFWR EQU 
+CVSTAT 
+ 

+CVFL1 
+CV1IVT 
+CV1I0AR EQU 
+CV1PGM EQU 
+CV1MRCDS EQU 
+CV1IRCDS EQU 
+CV1MAPIX EQU 
+CV1MAPVT EQU 
+CV1MAPVL EQU 
+CVFL2 DS 
+CV2HIVIE EQU 
+CV2VRF EQU 
+CV2CNT EQU 
+CV2RCVR EQU 
+CV2SRCH EQU 
+CV2DSNLY EQU 
+CV2VER EQU 
+CV2NLEVL EQU 
+* 
+ DS 



DS 

DS 
EQU 



OF 

CL4 

H 

XL1 

X'OT 

X'02' 

X'03' 

X'04' 

X'05' 

X'06' 

X'07' 

X'08' 

X'09' 

X'OA' 

X'OB' 

X'OC 

X'OD' 

XL1 

XL1 

X'80' 

X"40' 

X'20' 

X'10' 

X'08' 

X'04' 

X'02' 

X'01 ' 

XL1 

X'80' 

X'40' 

X'20' 

X'10' 

X'08' 

X'04' 

X'02' 

X'01 ' 

H 



CVAF PARAMETER LIST 

EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION BYTE 

CVAFDIR ACCESS=READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST 

BELOW) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 
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+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CWRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


♦-CVPLMAP 



UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VI XM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



+* VALUES OF CVSTAT 

+*{THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
END 
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Example 5: Using the CVAFSEQ Macro mth a Nonindexed VTOC 



This example reads as many as five DSCBs in physical-sequential order. The 
address of the UCB is suppUed to the program in register 5 (labeled RUCB). 
The address of a parameter list is supplied in register 4 (labeled RLIST). The 
first word of the parameter list contains the address of a 5-b5rte field. On entry, 
this field is set to zero if no previous DSCBs have been read; otherwise, the field 
is set to the CCHHR of the last DSCB read. This 5-byte field is supplied by the 
caller of this program and is not modified by this program. 

The remainder of the parameter list consists of one or more 2-word entries, to a 
maximum of five 2-word entries. The first word of each entry contains the 
address of a 140-byte DSCB buffer. The second word contains the address of a 
5-byte field that is to contain the CCHHR of the DSCB. 

A buffer Ust with five buffer list entries is contained in the program. The 
ICVAFBFL macro generates the buffer list header and one buffer list entry. 
The remaining buffer list entries are generated following the ICVAFBFL macro. 

The CVAFSEQ macro is used once in the program to read as many DSCBs as 
there are 2-word entries in the parameter list. The buffer list header field 
BFLHNOE is initialized with the number of buffer list entries that CVAFSEQ is 
to process. The number matches the number of 2-word entries in the parameter 
list supplied to this program. 

After the CVAFSEQ call, the CCHHR for each DSCB read is moved from the 
buffer list entry field BFLEARG to the field whose address is supplied by the 
caller of the program. If the BFLEARG field is zero, the previous DSCB read 
was the last in the VTOC. 

The BFLEARG in the first buffer Ust entry is initialized with the CCHHR 
supplied by the caller: its address is the third word in the parameter Ust. This 
CCHHR serves as the starting place for the CVAFSEQ caU. DSCBs with a 
CCHHR greater than the suppUed CCHHR are read. 

This program must be APF authorized. 



CSECT 




STM 


14,12,12(13) 


BALR 


12,0 


USING 


*,12 


ST 


1 3 , SAVEAREA+4 


LA 


RWORK,SAVEAREA 


ST 


RWORK,8{,13) 


LR 


1 3 , RWORK 



Appendix B. Examples of VTOC Access Macros 285 



* 

* REGISTERS 

* 

REG1 EQU 1 REGISTER 1 

RWORK EQU 3 WORK REGISTER 

RLIST EQU 4 ADDRESS OF PARM LIST 

RUCB EQU 5 UCB ADDRESS 

RCURRENT EQU 6 CURRENT ENTRY IN PARM LIST 

RBLE EQU 7 CURRENT BUFFER LIST ENTRY 

RCOUNT EQU 8 COUNT OF ENTRIES IN BUFFER LIST 

REGIS EQU 15 RETURN CODE REGISTER 15 

* 

* READ UP TO 5 DSCBS . 

* RUCB CONTAINS ADDRESS OF UCB. 

* RLIST CONTAINS ADDRESS OF PARAMETER LIST. 

* WORD = ADDRESS OF CCHHR OF LAST DSCB READ. THIS DSCB IS 

* NOT TO BE READ 

* WORD 1 = ADDRESS OF DSCB BUFFER. 

* WORD 2 = ADDRESS OF CCHHR OF DSCB READ. 

* W0RD1 AND W0RD2 REPEATED UP TO 4 TIMES. 

* HIGH ORDER BIT OF WORD 2 SET TO ONE FOR LAST ENTRY. 
* 

USING LIST, RLIST ADDRESSABILITY TO PARM LIST 

XC BFLHDR(BFLHLN+5*BFLELN) ,BFLHDR ZERO BUFFER LIST WITH * 

5 BUFFER LIST ENTRIES 
01 BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
LA RCURRENT, LI STPRMS FIRST DOUBLEWORD ENTRY IN PARM LIST 
USING LI STPRMS, RCURRENT USING ON DOUBLEWORDS 
LA RBLE,BFLE FIRST BUFFER LIST ENTRY 

USING BFLE,RBLE 

L RWORK, LISTSTRT ADDRESS OF STARTING CCHHR 
MVC BFLEARG,0 (RWORK) MOVE STARTING CCHHR INTO FIRST * 

BUFFER LIST ENTRY 
XR RCOUNT, RCOUNT ZERO COUNT 
BUFLOOP EQU * PUT BUFFER ADDRESSES IN BUFFER LIST * 

ENTRIES 
LA RCOUNT, 1 (, RCOUNT) INCREMENT COUNT 
L RWORK, LISTBUF ADDRESS OF DSCB BUFFER 
ST RWORK, BFLEBUF-BFLE(, RBLE) PLACE IN BUFFER LIST 
MVI BFLELTH-BFLE(RBLE) ,DSCBLTH FULL DSCB READ 
TM LISTLAST,LASTBIT IS IT LAST ENTRY IN LIST 
LA RCURRENT, LI STNEXT INCREMENT TO NEXT ENTRY IN LIST 
LA RBLE, BFLELN(, RBLE) INCREMENT TO NEXT BUFFER LIST ENTRY 
BZ BUFLOOP LOOP TO PUT NEXT BUFFER IN BFLE 

STC RCOUNT, BFLHNOE SET NUMBER OF ENTRIES IN BUFFER * 

LIST HEADER 
DROP RCURRENT, RBLE 

* READ UP TO 5 DSCBS WHOSE CCHHR IS GREATER THAN THE CCHHR IN 

* THE FIRST BUFFER LIST ENTRY 

* 
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CVAFSEQ UCB=(RUCB), 
BRANCH=YES , 
MF=(E,CVPL) 

LA 1 , CVPL 



CALL CVAF 
BRANCH ENTER 



LOAD PARAMETER REG 1 



+ 


ST RUCB,12(,1) 


+ 


L 15,16 


+ 


L 15,328(,15) 


+ 


L 15,12(,15) 


+ 


L 15,0(,15) 


+ 


BALR 14,15 




USING CVPL, REG 1 




LTR REGIS, REGIS 




BZ MOVECHR 



STORE UCB PTR IN PARM LIST 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVAF TABLE ADDRESS 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 
ADDRESSABILITY TO CVPL 
ANY ERROR 
BRANCH IF MOVE IN CCHHRS 

* DETERMINE WHAT ERROR IS 

* 

C REG15,ERROR4 IS RETURN CODE 4 

BNE OTHERERR BRANCH IF NOT 4 

CLI CVSTAT,STAT032 IS IT END OF DATA? 

BNE OTHERERR BRANCH IF NOT 

DROP REG1 ADDRESSABILITY TO CVPL NOT NEEDED 

* DETERMINE IF ANY DSCBS HAVE BEEN READ. BFLEARG IS NON-ZERO 

* IN EACH BUFFER LIST ENTRY FOR WHICH A DSCB HAS BEEN READ 

* 



MOVECHR EQU * 

LA RCURRENT , LI STPRMS 
USING LI STPRMS, RCURRENT 
LA RBLE,BFLE 
USING BFLE,RBLE 



CHRLOOP 


EQU 


* 




L 


RWORK,LISTCHR 




XC 


( L ' BFLEARG , RWORK ) 




NC 


BFLEARG , BFLEARG 




BZ 


EXIT 




MVC 


0(L' BFLEARG, RWORK) 




TM 


LISTLAST,LASTBIT 




BO 


EXIT 




LA 


RCURRENT , LISTNEXT 




LA 


RBLE , BFLELN ( , RBLE ) 




B 


CHRLOOP 


EXIT 


EQU 


* 




L 


1 3 , SAVEAREA+4 




RETURN (14,12) 




LM 


14,12,12(13) 




BR 


14 


OTHERERR 

* 
41 


EQU 


» 


* 


B 


EXIT 


ERR0R4 


DC 


F'4' 



IS DATA SET NAME GREATER THAN DSN2 
FIRST ENTRY IN PARM LIST 

FIRST BUFFER LIST ENTRY 

MOVE CCHHR ARGUMENT TO CALLER AREA 

ADDRESS OF CCHHR OF CALLER 
(RWORK) ZERO CALLER CCHHR AREA 

IS CCHHR ZERO 

BRANCH IF YES -NO MORE DSCBS 
fLEARG MOVE CCHHR TO CALLER AREA 

LAST ENTRY IN PARM LIST? 

BRANCH IF YES 

NEXT ENTRY IN LIST 

NEXT BUFFER LIST ENTRY 

TEST NEXT BFLE 

RETURN TO CALLER 



RESTORE THE REGISTERS 
RETURN 



ICVAFBFL DSECT=NO 



ERROR PROCESSING 



RETURN 

RETURN CODE 4 

BUFFER LIST WITH ONE BUFFER LIST 

ENTRY 
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+• BUFFER LIST HEADER 



+BFLHDR 


DS 


OF 


+BFLHNOE 


DS 


XL1 


+BFLHFL 


DS 


XL1 


+ 


ORG 


BFLHFL 


+BFLHKEY 


DS 


XL1 


+BFLHVIR 


EQU 


X'08' 


+BFLHDSCB 


EQU 


X'04' 


+ 


DS 


XL1 


+BFLHSP • 


DS 


XL1 


+BFLHFCHN 


DS 


A 


+* 






+BFLHLN 


EQU 


♦-BFLHDR 



BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 

PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 

BUF. LIST ENTRIES DESCRIBE DSCBS 

RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 

FORWARD CHAIN PTR TO NEXT BUF. 

LIST 

LENGTH OF BUFFER LIST HEADER 



+* BUFFER LIST ENTRY 



+BFLE 


DS 


OF 


+BFLEFL 


DS 


XL1 


+BFLERBA 


EQU 


X'80' 


+BFLECHR 


EQU 


X'40' 


+BFLETTR 


EQU 


X'20' 


+BFLEAUPD 


EQU 


X'10' 


+BFLEMOD 


EQU 


X'08' 


+BFLESKIP 


EQU 


X'04' 


+BFLEIOER 


EQU 


X'02' 


+ 


DS 


XL1 


-V-BFLELTH 

+* 

+BFLEARG 


DS 


XL1 


DS 


XLS 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XL3 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL4 


+BFLEBUF • 


DS 


A 


+BFLELN • 


EQU 


♦-BFLE 




DS 


CL(4*BFLELN) 


SAVEAREA 


DS 


18F 


DSC6 


DSECT 




IECSDSL1 ( 1 ) 


+IECSDSL1 


EQU 


* 


+IECSDSF1 


EQU 


IECSDSL1 


+DS1DSNAM 


DS 


CL44 


+DS1FMTID 


DS 


CL1 


+DS1DSSN 


DS 


CL6 


+DS1V0LSQ 


DS 


XL2 


+DS1CREDT 


DS 


XL3 


+DS1EXPDT 


DS 


XL3 


+DS1N0EPV 


DS 


XL1 


+DS 1 NOBDB 


DS 


XL1 


+♦ 






+ 


DS 


XL1 


+DS1SYSCD 


DS 


CL13 


+ 


DS 


XL7 


+DS 1 DSORG 


DS 


XL2 



BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

'TTR' OF ARGUMENT 

•RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
FOUR BUFFER LIST ENTRIES 
SAVE AREA 

FORMAT 1 DSCB DATASET NAME AND 

DATA 

FORMAT 1 DSCB 

DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 
DATA SET ORGANIZATION 
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+* 

+DS1DSGIS 
+♦ 

+DS1DSGPS 
+* 

+DS 1 DSGDA 
+DS1DSGCX 
+* 
+* 

+DS1DSGP0 
+DS 1 DSGU 
+♦ 
+* 
+* 
+♦ 

+DS1DSGGS 
+DS 1 DSGTX 
+DS 1 DSGTQ 
+* 

+DS1ACBM 
+DS 1 DSGTR 
+* 
+* 

+DS1RECFM 
+DS 1 OPTCD 
+DS 1 BLKL 
+DS 1 LRECL 
+DS1KEYL 
+DS 1 RKP 
+DS1DSIND 
+DS 1 SCALO 
+DS 1 LSTAR 
+DS 1 TRBAL 
+ 

+DS1EXT1 
+* 
+* 
+* 
+* 

+DS1EXT2 
+DS1EXT3 
+DS 1 PTRDS 
+DS 1 END 
DSCBLTH 
LIST 

LISTSTRT 
LISTPRMS 
LISTBUF 
LISTCHR 
LISTLAST 
LASTBIT 



FIRST BYTE OF DS1DS0RG 

EQU X'80' IS - INDEXED SEQUENTIAL 301 A 

ORGANIZATION 

EQU X'40' PS - PHYSICAL SEQUENTIAL 301 A 

ORGANIZATION 

EQU X'20' DA - DIRECT ORGANIZATION 301 A 

EQU X'10' CX - BTAM OR QTAM LINE GROUP 301 A 

EQU X'08' RESERVED 301 A 

EQU X'04' RESERVED 301 A 

EQU X'02' PO - PARTITIONED ORGANIZATION 301 A 

EQU X'01' U - UNMOVABLE, THE DATA 301 A 

CONTAINS LOCATION DEPENDENT 

INFORMATION 



SECOND BYTE 
EQU X'80' 
EQU X ' 40 ' 
EQU X'20' 
EQU X'10' 
EQU X'08' 
EQU X ' 04 ' 
EQU X'02' 
EQU X'01' 
DS XL1 
DS XL1 
DS XL2 
DS XL2 
DS XL1 
DS XL2 
DS XL1 
DS XL4 
DS XLS 
DS XL2 
DS XL2 
DS XL10 
FIRST BYTE 
SECOND BYTE 
THIRD - SIXTH BYTES 
SEVENTH - TENTH BYTES 



301A 
301A 
301A 
301A 
301A 
301A 
301A 
301A 



DS 

DS 

DS 

EQU 

EQU 

DSECT 

DS 

EQU 

DS 

DS 

DS 

EQU 

DS 

EQU 

CSECT 



XL10 
XL10 
XLS 

* 

*-IECSDSL1 

F 

« 

F 

OF 

X 

X'80' 

AL3 

* 



OF DS1DS0RG 
GS - GRAPHICS ORGANIZATION 
TX - TCAM LINE GROUP 
TQ - TCAM MESSAGE QUEUE 
RESERVED 

ACCESS METHOD CONTROL BLOCK 
TR - TCAM 3705 
RESERVED 
RESERVED 
RECORD FORMAT 
OPTION CODE 
BLOCK LENGTH 
RECORD LENGTH 
KEY LENGTH 

RELATIVE KEY POSITION 
DATA SET INDICATORS 
SECONDARY ALLOCATION 
LAST USED TRACK AND BLOCK ON TRACK 
BYTES REMAINING ON LAST TRACK USED 
RESERVED 

FIRST EXTENT DESCRIPTION 
EXTENT TYPE INDICATOR 
EXTENT SEQUENCE NUMBER 
LOWER LIMIT 
UPPER LIMIT 

SECOND EXTENT DESCRIPTION 
THIRD EXTENT DESCRIPTION 
POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 

LENGTH OF DSCB 
PARAMETER LIST 
ADDRESS OF CCHHR TO START SEARCH 

BUFFER ADDRESS 

ADDRESS OF CCHHR FIELD 

BYTE 

LAST DOUBLE WORD 

3 BYTE ADDRESS OF CCHHR 

NEXT DOUBLEWORD 



^Kcjlc************************ 



LISTNEXT 
EXAMPLES 

4t * 4c # « * 4e * 

* 
* 



READ DSCBS WITH CCHHR GREATER THAN THE CCHHR IN THE FIRST 
BUFFER LIST ENTRY - 
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CVPL 



CVAFSEQ ACCESS=GT, 







BUFLIST=BFLHDR, 






MF=L 


+ 


CNOP 


0,4 


+CVPL 


EQU 


* 


+ 


DC 


CL4 • CVPL ' 


+ 


DC 


AL2(ICV6E-CVPL) 


+ 


DC 


XL1'04' 


+ 


DC 


XL1 '00' 


+ 


DC 


B'00100000' 


+ 


DC 


B'OOOOOOOO' 


+ 


DC 


H'O' 


+ 


DC 


A{0) 


+ 


DC 


A(0) 


+ 


DC 


A(BFLHDR) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A{0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ICV6E 


EQU 


* 




ORG 


CVPL 



ADDRESS OF BUFFER LIST 



CVPLMAP ICVAFPL DSECT=NO 



EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION CODE 

STATUS INFORMATION 

FIRST FLAG BYTE 

SECOND FLAG BYTE 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 
EXPAND MAP OVER LIST 
CVPL MAP 



+* CVAF PARAMETER LIST 



+CVPLMAP 


DS 


OF 


+CVLBL 


DS 


CL4 


+CVLTH 


DS 


H 


+CVFCTN 


DS 


XL1 


+CVDIRD 


EQU 


x'or 


+CVDIWR 


EQU 


X'02' 


+CVDIRLS 


EQU 


X'03' 


+CVSEQGT 


EQU 


X'04' 


+CVSEQGTE 


EQU 


X'05' 


+CVDMIXA 


EQU 


X'06' 


+CVDMIXD 


EQU 


X'07' 


+CVDMALC 


EQU 


X'08' 


+CVDMRLS 


EQU 


X'09' 


+CVDMMAP 


EQU 


X'OA' 


+CWOL 


EQU 


X'OB' 


+CWRFRD 


EQU 


X'OC 


+CWRFWR 


EQU 


X'OD' 


+CVSTAT 

+ 

+CVFL1 


DS 


XL1 


DS 


XL1 


+CV1IVT 


EQU 


X'80' 


+CV1I0AR 


EQU 


X'40' 


+CV1PGM 


EQU 


X'20' 


+CV1MRCDS 


EQU 


X'10' 



CVAF PARAMETER LIST 

EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION BYTE 

CVAFDIR ACCESS=READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST 

BELOW) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 
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+CV1IRCDS 


EQU 


X'08' 


+CV1MAPIX 


EQU 


X'04' 


+CV1MAPVT 


EQU 


X'02' 


+CV1MAPVL 


EQU 


X'OT 


+CVFL2 


DS 


XL1 


+CV2HIVIE 


EQU 


X'80' 


+CV2VRF 


EQU 


X'40' 


+CV2CNT 


EQU 


X'20' 


+CV2RCVR 


EQU 


X'lO' 


+CV2SRCH 


EQU 


X'08' 


+CV2DSNLy 


EQU 


X'04' 


+CV2VER 


EQU 


X'02' 


+CV2NLEVL 


EQU 


X'01 ' 


+♦ 






+ 


DS 


H 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CWRPDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


♦-CVPLMAP 



IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VI XM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



+* VALUES OF CVSTAT 

+*(THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
END 
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Example 6: Using the CVAFTST and CVAFDSM Macros 



This example returns a format-5 DSCB to the caller. The format-5 DSCB is 
constructed by this program if the volume contains an indexed VTOC. The 
format-5 DSCB is read by another program, F5RTN (not described in the 
example), if the volimie contains a nonindexed VTOG. 

The CVAFTST macro is used to determine if a nonindexed VTOC is on the 
volume. 

If the CVAFTST return code is neither nor 4 (a nonindexed VTOC is on the 
volimie), the CVAFDSM macro is issued to obtain up to 27 extents from the 
VPSM in the VTOC index. The program does not determine whether the 
CVAFTST return code is 8 (volume contams indexed VTOC) or 12 (it cannot 
be determined what type of VTOC is on the volume). In either case, the 
CVAFDSM macro is issued. If the CVAFTST return code is 12, the 
CVAFDSM macro call will cause CVAF to determine whether an indexed or a 
nonindexed VTOC is on the volume, and the CVIIVT bit will be set to one or 
zero, accordingly. 

The extent table (at label EXTABL) is initialized to request 27 extents from the 
CVAFDSM macro, which is one more than the number of extents that fit in a 
format-5 DSCB. The format-5 DSCB is constructed from the first 26 extents 
returned from the CVAFDSM call. 

The first extent in the extent table is initialized from the last extent in the 
format-5 DSCB area supplied by the caller of the program. If this is the first 
call, the program assumes that the format-5 area is initialized to zero. Thus, the 
first extent in the extent table has a value of zero to serve as the starting place 
for the extent search. If this is the second or subsequent caU, the last extent in 
the format-5 area would be the last extent obtained from the previous 
CVAFDSM call. 

The format-5 chain pointer field (DS5PTRDS) is set to a nonzero value if 
CVAFDSM returned a 27th extent. In this case, the program will be called 
again to obtain another format-5 DSCB. 

The program's return code is if no errors were encountered and 4 if an error 
was encountered. 

This program must be APF authorized. 



EXAMPLES 


CSECT 






STM 


14,12,12(13) 




BALR 


12,0 




USING 


*,12 




ST 


1 3 , SAVEAREA+4 




LA 


RWORK,SAVEAREA 




ST 


RWORK,8(,13) 




LR 


1 3 , RWORK 



292 MVS/XA System-Data Administration 



* REGISTERS 

« 

RDEB EQU 3 

RUCB EQU 4 

RF5 EQU 5 



RWORK 
REGIS 

KF5 

* 
* 
* 
* 
* 
* 
* 



+ 
+ 
+ 
+ 
+ 

+ 
+ 

+ICV1E 



4c 
* 



EQU 
EQU 



6 
15 



DEB ADDRESS SUPPLIED BY CALLER 

UCB ADDRESS SUPPLIED BY CALLER 

ADDRESS OF FORMAT 5 BUFFER SUPPLIED 

BY CALLER 

WORK REGISTER 

RETURN CODE REGISTER 15 



EQU 26 NUMBER OF FORMAT 5 EXTENTS 

READ FORMAT 5 DSCB OR BUILD A FORMAT 5 DSCB IF 

AN INDEXED VTOC 
UCB ADDRESS SUPPLIED IN RUCB. 
RF5 CONTAINS THE ADDRESS OF THE FORMAT 5 DSCB BUFFER. IT 

CONTAINS THE LAST FORMAT 5 DSCB READ OR BUILT. THE FORMAT 5 

BUFFER IS ZERO IF THIS IS THE FIRST CALL 
IF THE FORMAT 5 DSCB BUFFER RETURNED TO THE CALLER HAS A 

NONZERO VALUE IN DS5PTRDS, THIS ROUTINE WILL BE CALLED 

AGAIN TO OBTAIN THE NEXT FORMAT 5 DSCB. 



USING IECSDSF5,RF5 

CVAFTST UCB=(RUCB) 

CNOP 0,4 

LR 1 , RUCB 

L 15,16 

L 15,328(,15) 

L 15,12(,15) 

LTR 15,15 

BZ ICV1E 

L 15,4(,15) 

BALR 14,15 

EQU * 

LTR REG15,REG15 

BZ UNINDXD 

C REG15,N0TIXRC 

BE UNINDXD 



ADDRESSABILITY TO FORMAT 5 BUFFER 

TEST VTOC 

START OF CVAFTST MACRO 

LOAD PARAMETER REG 1 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVAF TABLE ADDRESS 
TEST FOR ZERO VALUE 
CVAF IS NOT ON THE SYSTEM 
LOAD POINTER TO CVAF TEST E.P. 
BRANCH AND LINK TO CVAF TEST 
END OF CVAFTST 

READ NEXT FORMAT 5 
UNINDEXED VTOC? 
READ NEXT FORMAT 5 



ASSUME INDEXED VTOC UNLESS CVAFDSM CALL INDICATES UNINDEXED 

MVC EXTS(L'DS5AVEXT) ,DS5MAVET+L'DS5MAVET-L'DS5AVEXT MOVE THE 

LAST EXTENT FROM FORMAT 5 TO FIRST 
ENTRY IN THE EXTENT TABLE 
CVAFDSM MF=(E,CVPL), GET 27 EXTENTS FROM CVPL 
UCB={RUCB), RUCB ADDRESS REQUIRED 
DEB=(RDEB), RDEB ADDRESS REQUIRED BY 

UNAUTHORIZED PROGRAMS CALLING CVAF 
BRANCH=YES BRANCH ENTRY CALL 
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NOERROR 



UNINDXD 



RETURN 



LA 

L 

L 

L 

L 

BALR 

TM 

BZ 

LTR 

BZ 

C 

BNE 

CLI 

BNE 

EQU 

MVC 

MVC 

MVI 
MVC 

XR 
XC 

NC 



BZ 
MVI 

B 
EQU 



1,CVPL 

15,16 

15,328(,15) 

15,12(,15) 

15,0(,15) 

14,15 
CVFL1,CV1IVT 
UNINDXD 
REG15,REG15 
NOERROR 
REG15,RC04 
OTHERERR 
CVSTAT,STAT032 
OTHERERR 



LOAD PARAMETER REG 1 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVAF TABLE ADDRESS 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 

IS THIS INDEXED VTOC 

READ FORMAT 5 IF NOT 

ANY ERROR 



UNEXPECTED ERROR 
END OF DATA 
UNEXPECTED ERROR 
* BUILD FORMAT 5 

DS5KEYID,F5ID 
DS5AVEXT(L'DS5AVEXT+L'DS5EXTAV) ,EXTS MOVE IN EXTENTS » 

TO DS5FMTID 
DS5FMTID,C'5' 
DS5MAVET,EXTS+L'DS5AVEXT+L'DS5EXTAV MOVE REMAINING * 

EXTENTS 
REG 15, REG 15 RETURN CODE ZERO 

DS5PTRDS,DS5PTRDS ZERO CHAIN POINTER 

EXTS+L ' EXTS-L ' DS5AVEXT ( L ' DS5AVEXT) , EXTS+L ' EXTS-L ' DS5AVEXT* 

IS LAST(27TH) EXTENT FROM CVAF ♦ 
ZERO? 

BRANCH IF YES-LEAVE DS5PTRDS ZERO 
1,1 SET DS5PTRDS NONZERO TO SIMULATE * 
THERE BEING ANOTHER FORMAT 5 

CALL ROUTINE TO READ NEXT FORMAT 5 
LINK TO FORMAT 5 ROUTINE. RETURN * 
CODE PASSED BACK IN REG15 

LOAD SUP.PARAMLIST ADR 
ADDR OF EP PARAMETER 
DCB ADDRESS PARAMETER LCOA 
EP PARAMETER 
ISSUE LINK SVC 
RETURN TO CALLER 



RETURN 

DS5PTRDS+L ' DS5PTRDS- 

RETURN 

* 



LINK EP=F5RTN 



0,4 

15,*+20 

A(*+8) 

A(0) 

CL8'F5RTN' 

6 

1 3 , SAVEAREA+4 



CNOP 

BAL 

DC 

DC 

DC 

SVC 

EQU 

L 

RETURN (14,12) ,RC=(15) 



OTHERERR 



DSCB 

+IECSDSL5 

+IECSDSF5 

+DS5KEYID 

+DS5AVEXT 

+ * 

+* 

+* 

+♦ 



L 

LM 

BR 

EQU 

L 

B 

DSECT 

lECSDSLl 

EQU 

EQU 

DS 

DS 

BYTES 



14,12(13,0) 
0,12,20(13) 
14 

* 

REG15,RC04 
RETURN 



RESTORE REGISTER 14 
RESTORE THE REGISTERS 
RETURN 

ERROR 

ERROR RETURN CODE 



(5) 



BYTES 
BYTE 



IECSDSL5 
XL4 
XL5 
1 - 2 

3-4 
5 



FORMAT 5 DSCB 

KEY IDENTIFIER 

AVAILABLE EXTENT 
RELATIVE TRACK ADDRESS OF THE FIRST TRACK 
IN THE EXTENT 

NUMBER OF UNUSED CYLINDERS IN THE EXTENT 
NUMBER OF ADDITIONAL UNUSED TRACKS 
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+DS5EXTAV 
+DS5FMTID 
+DS5MAVET 
+DS5PTRDS 
+DS5END 

EXAMPLES 

NOTIXRC 

RC04 

F5ID 

SAVEAREA 

EXTABL 

EXTNO 

EXTS 

CVPL 



DS 

DS 

DS 

DS 

EQU 

CSECT 

DC 



XL35 
CL1 
XL90 
XLS 

« 



SEVEN AVAILABLE EXTENTS 
FORMAT IDENTIFIER 
EIGHTEEN AVAILABLE EXTENTS 
POINTER TO NEXT FORMAT 5 DSCB 



DC 
DC 
DS 
DS 
DC 
DS 



F'4' 

F'4' 

XL4' 0505050505' 

18F 



CVAFTST RETURN CODE-UNINDEXED 
RETURN CODE 4 
FORMAT 5 FIELD, DS5KEYID 
REGISTER SAVE AREA 
0CL(1+(KF5+1)*L'DS5AVEXT) EXTENT TABLE 
AL1(KF5+1) NUMBER OF EXTENTS IN TABLE 

CL( (KF5+1 ) *L'DS5AVEXT) EXTENTS 
CVAFDSM ACCESS=MAPDATA, 

COUNT=NO, DO NOT COUNT EXTENTS 

MAP=VOLUME, ACCESS VOLUME SPACE MAP 

EXTENTS=EXTABL, EXTENT TABLE ADDRESS 
MF=L LIST FORM OF MACRO 



+ 


CNOP 


0,4 


+CVPL 


EQU 


* 


+ 


DC 


CL4 • CVPL • 


+ 


DC 


AL2 (ICV9E-CVPL) 


+ 


DC 


XL1 'OA' 


+ 


DC 


XLI'OO' 


+ 


DC 


B'ooioooor 


+ 


DC 


B'OOOOOOOO* 


+ 


DC 


H'O' 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A (EXTABL) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ICV9E 


EQU 


* 




ORG 


CVPL 


CVPLMAP 


ICVAFPL DSECT=NO 


4.**4t********««*«««4i«*«*«*««4t*4i* 


+ ♦ 


CVAF 


PARAMETER LIST 


^.«»»«»«««*»»«««»»»»»»»»*»»»»*»* 


+CVPLMAP 


DS 


OF 


+CVLBL 


DS 


CL4 


+CVLTH 


DS 


H 


+CVFCTN 


DS 


XL1 


+CVDIRD 


EQU 


X'OT 


+CVDIWR 


EQU 


X'02' 


+CVDIRT,S 


EQU 


X'03' 


+CVSEQGT 


EQU 


X'04' 


+CVSEQGTE 


EQU 


X'05' 


+CVDMIXA 


EQU 


X'06' 


+CVDMIXD 


EQU 


X'07' 


+CVDMALC 


EQU 


X'08' 


+CVDMRLS 


EQU 


X'09' 


+CVDMM7^ 


EQU 


X'OA' 



EBCDIC 'CVPL' 
LENGTH OF CVPL 
FUNCTION CODE 
STATUS INFORMATION 
FIRST FLAG BYTE 
SECOND FLAG BYTE 
RESERVED 
UCB ADDRESS 
DATA SET NAME ADDRESS 
BUFFER LIST ADDRESS 
INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 
DEB ADDRESS 
ARGUMENT ADDRESS 
SPACE PARAMETER LIST ADDRESS 
EXTENTS TABLE ADDRESS 
NEW VRF VI XM BUFFER LIST ADDR 
VRF DATA ADDRESS 
COUNT AREA ADDRESS 
END OF CVPL 
OVERLAY CVPL WITH EXPANSION OF MAP 



CVAF PARAMETER LIST 
EBCDIC 'CVPL' 
LENGTH OF CVPL 
FUNCTION BYTE 
CVAFDIR ACCESS=READ 
CVAFDIR ACCESS=WRITE 
CVAFDIR ACCESS=RLSE 
CVAFSEQ ACCESS=GT 
CVAFSEQ ACCESS=GTEQ 
CVAFDSM ACCESS=IXADD 
CVAFDSM ACCESS=IXDLT 
CVAFDSM ACCESS=ALLOC 
CVAFDSM ACCESS=RLSE 
CVAFDSM ACCESS=MAPDATA 
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+CWOL 


EQU 


X'OB' 


+CWRFRD 


EQU 


X'OC 


+CWRFWR 


EQU 


X'OD' 


+CVSTAT 


DS 


XL1 


+ 
+CVFL1 


DS 


XL1 


+CV1IVT 


EQU 


X • 80 ' 


+CV1I0AR 


EQU 


X'40' 


+CV1PGM 


EQU 


X'20' 


+CV1MRCDS 


EQU 


X'10' 


+CV1IRCDS 


EQU 


X'08' 


+CV1MAPIX 


EQU 


X'04' 


+CV1MAPVT 


EQU 


X'02' 


+CV1MAPVL 


EQU 


X'01 ' 


+CVFL2 


DS 


XL1 


+CV2HIVIE 


EQU 


X'80' 


+CV2VRF 


EQU 


X'40' 


+CV2CNT 


EQU 


X'20' 


+CV2RCVR 


EQU 


X'10' 


+CV2SRCH 


EQU 


X'08' 


+CV2DSNLY 


EQU 


X'04' 


+CV2VER 


EQU 


X'02' 


+CV2NLEVL 
+* 

+ 


EQU 


X'01 ' 


DS 


H 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CVVRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


*-CVPLMAP 


+ * 




VALUES OF CVSTAT 


+*(THIS PART OF 


THE ICVAFPL MACRO 




END 





CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST 

BELOW) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



EXPANSION IS NOT SHOWN) 
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Appendix C. VTOC Index Error Message and Associated Codes 



Error Message 



When CVAF finds an error in a VTOC index, it issues this message: 



IEC606I VTOC INDEX DISABLED ON dev.volser, 
code,[rba[,secno,offset]] 



Explanation 



System Action 



In addition, CVAF puts a return code in the CVSTAT field of the CVPL. 



The Common VTOC Access Facility (CVAF) detected a VTOC index error on 
the device "dev" with volume serial number "volser." "code" is a number that 
represents the kind of VTOC index error encountered, "rba" is the RBA of the 
VIR in the VTOC index that contains a structure error indicated by "code." If 
the VIR is a VIER, the section number in the VIER containing the VTOC index 
entry is supplied in "secno," and the offset into the section of that VTOC index 
entry is supplied in "offset." 



The VTOC index is disabled by zeroing the index bit in the format-4 DSCB and 
setting the bit in the first high-level VIER that indicates invalid VTOC index 
structure. The VTOC will be converted to nonindexed format when DADSM 
next allocates space on the volume. A system dump is written to the 
SYSl.DUMP data set, and an entry is made in the SYSl.LOGREC data set. 
The message IEC604I (which indicates that the VTOC convert routines have 
been used) will be issued later. 
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Programmer Response 



Examine the system dump and a print of the VTOC index, and use the 
information in message IEC606I to deteimine the cause of the VTOC index 
structure error. 



Routing and Descriptor Codes 



The routing codes are 4 (direct access pool) and 10 (system/error maintenance), 
and the descriptor code is 4 (system status). 



Codes Put in the CVSTAT Field 

Code Meaning 

O(X'OO') No error. 

1 (X ' 1 ' ) Data set name not found, or VIER is empty. 

2(X ' 02 ' ) Argument is outside VTOC extents or RBA range of VTOC index. 

4(X'04') Invalid parameter supplied (wrong key), or VRFAREA too small. 

5 (X • 05 ' ) DSN keyword omitted. 

6(X ' 06 ' ) Not authorized to perform this function. 

7(X' 07 ' ) Buffer Ust omitted. 

8(X'08') DEB invalid or omitted or not open to VTOC. 

9(X'09') IOAREA=KEEP and user not authorized, or I/O area supplied and either user not authorized or 
CVAFVOL function. 

10(X'0A' ) Function not supported on OS VTOC. 

ll(X'OB') DSCB is not format-0 DSCB and VERIFY=YES. 

12(X'0C') MAPRCDS=YES and/or DCRCDS^KEEP but VTOC is nonindexed. 
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Code Meaning 

13(X'0D') IXRCDS=KEEP not specified for CVAFDSM ACCESS=IXADD or DCDLT. 

14(X'0E') CTAREA keyword omitted. 

1 5 (X ' OF • ) UCB invalid, volume not mounted; VIO unit, not DASD. 

1 7 (X ' 1 1 ' ) DSCB length invalid for the function requested : 96 bytes for C V AFDIR 

ACCESS=WRITE,VERIFY=YES; 140 bytes for CVAFSEQ reading in data set name 
sequence; 96 bytes for CVAFSEQ reading in physical sequence. 

19(X' 13') UCB omitted and CVAF I/O area not supplied. 

22 (X ' 1 6 ' ) Data set name already supplied in index . 

23(X' 17') Invalid DSN supplied (44 X'FF' is a reserved data set name). 

24(X' 18') ARG keyword not supplied. 

25(X' 19') Conflicting or incomplete information specified in the space table for a CVAFDSM 
ACCESS=ALLOC, MAP= VOLUME request. 

27(X' IB' ) VTOC index full. No free VIRs available and a VIER split is required. 

28(X' 1 C • ) Space keyword omitted (CVSPACE field zero in CVPL). 

29(X' ID') CVAFDSM ACCESS= ALLOC: No format DSCB available (MAP=VTOC), or VTOC index 
full (MAP=INDEX), or volume space not available (MAP=VOLUME). 

30(X' IE') CVAFDSM ACCESS= ALLOC: CCHHR (MAP=VTOC) or RBA MAPr=INDEX or volume 
space extent (MAP=VOLUME) akeady allocated. 

31(X' IF') CVAFDSM ACCESS= ALLOC or ACCESS=MAPDATA: CCHHR supplied outside VTOC 

extents (MAP=VTOC), or RBA outside VTOC index extents (MAP=INDEX), or volume space 
extent invalid or outside volume (MAP=VOLUME). 

32(X'20') End of data. CVAFDSM ACCESS=MAPDATA: no more free extents in VPSM. CVAFSEQ: 
no more names in index or DSCBs in VTOC. For indexed access, no DSN in VTOC index with 
higher or higher-or-equal key than that supplied. For physical-sequential access, no DSCB in the 
VTOC has a higher argument than that supplied. For a multiple DSCB request, the last DSCB in 
the VTOC was read and more DSCBs were requested. 
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Code Meaning 

3 3 (X ' 2 1 ' ) EXTENTS keyword omitted, or supplied number of extents is zero. 

34(X'22') CVAFDSM ACCESS=*RLSE and format-0 DSCB already free (MAP«VTOC), or VIER 
already unallocated (MAP=: INDEX) or volume space extent already unallocated 
(MAP^VOLUME). 

42(X • 2A ' ) VRF data supplied for write too long. 

43 (X' 2B • ) Buffer list is for VIRs, but a DSCB buffer list is required. 

44(X ' 2C • ) No buffer list entry found. 

45(X'2D') Invalid DSCB buffer length (neither 96 nor 140) m buffer list entry, or VIR buffer length not 
equal to VIB VIR size. 

46(X' 2E' ) Neither TTR nor CCHHR bits set in buffer list entry to be used in writmg or reading a 140-byte 
DSCB. 

47 (X ' 2F • ) More than one of the TTR, CCHHR, and RB A bits set in the buffer list entry. 

48 (X • 30 ' ) Both the DSCB and VIR bits set in the buffer list header. 

49(X' 31') RBA bit set in a buffer list entry for a DSCB buffer list. 

50(X' 32' ) TTR or CCHHR bit set in buffer list entry but buffer list header indicates buffer list is for a VIR. 

52(X ' 34 ' ) Combination of MAP and COUNT not supported. 

53(X'35') MAP omitted. 

54(X'36') Buffer list for a VIR chained to or from a buffer list for a DSCB. 

55(X'37') Unauthorized caller and VIB not initialized. 

56(X'38') MAPRCDS=YES not specified but required. 

57(X'39') Buffer list for a DSCB supplied, but buffer list for a VIR is required (in MAPRCDS or IXRCDS 
buffer list address in CVAF parameter list). 

58(X'3A') Neither the VIR nor DSCB bit set in a buffer list header. 
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Code Meaning 

60(X'3C') Invalid or conflicting setting of allocate option byte in space parameter 

61(X'3D') FUter criteria list address omitted (CVFCL=0) or ID not "FCL " (CVAFFILT). 

62(X' 3E' ) FCLCOUNT field is zero or no elements to process (CVAFFILT). 

63(X' 3F' ) FCLCOUNT field is greater than 1 and FCLILIST indicates a generic data set name 
(CVAFFILT). 

64(X'40') Insufficient number of user buffer list entries to complete this request. All data set names in the 
filter criteria list up to this point processed successfully. Use RESUME function to continue 
processing (CVAFFILT). 

65 (X ' 4 1 • ) Buffer list entry error, for example, buffer length not 1 40 bytes (CVAFFILT). 

66(X'42') ACCESS=RESUME and fUter save address (FSA) omitted (CVFSA=0), or FSA not in CVAF 
protect key (CVAFFILT). 

67(X'43') Invalid partially qualified data set name for generic access (CVAFFILT). 

68(X'44') Filter criteria list not in user key (CVAFFILT). 

69(X'45') Internal GETMAIN error (CVAFFILT). 

70(X'46' ) Direct VTOC access I/O error (CVAFFILT). 

71(X'47') Sequential VTOC access I/O error (CVAFFILT). 

72(X'48') Error in CVAFFILT processing. RESUME function not recommended (CVAFFILT). 

73(X'49') Insufficient number of user buffer list entries to complete this request. Error in DSCB chain. One 
or more names in the filter criteria list not processed successfully; however, RESUME function 
recommended for remaining DSCBs (CVAFFILT). 

74(X'4A') Data set name information is invalid (FCLDSNLG is either "0" or greater than '44', or 
FCLDSNA is either "0" or not in user key) (CVAFFILT). 

127(X'7F') I/O error occurred. 

128(X'80') Reserved. 
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Code Meaning 

129(X' 81*) The first high-level VEER as indicated in the VDCM does not have the flag bit set indicating it is 
the first high-level VIER. 

1 30(X • 82 • ) A horizontal or vertical VEER pointer is outside the RBA range of the VTOC index. 

1 3 1 (X' 83 ' ) A vertical VffiR pointer pomts to a VIR that is not a VffiR (mvalid ED in header). 

132(X'84*) A level n vertical index entry pointer points to a VEER that is not at level n - 1. 

133(X'85') Level n horizontal index entry pointer points to VEER that is not at level n. 

134(X'86') Horizontal VEER/map pointer points to a VER that is not a VBER/map (invalid ID in header). 

135(X*87') Horizontal map pointer points to VER that is not one of the first n VTOC index records (n is 
recorded in VIXM field VIMRCDS), or the first record in the VTOC index is not a VIXM. 

136(X'88') A level-1 index entry contams a CCHHR pointer that is outside the VTOC extent. 

137(X'89*) The first high-level VIER, as indicated in the VDB, does not have the flag bit set indicating it is 
the first high-level VIER. (This error is either recovered from by updating the VEB from the 
VIXM, or the error is changed to 129.) 

138(X'8A*) The RBA of the VTOC mdex VIR does not match the RBA recorded in the header of the 
record. 

139(X'8B') The first record of a map (VKM, VPSM, or VMDS) is not one of the first n VTOC mdex 
records (n is recorded in the VIXM field, VIMRCDS). 

140(X'8C*) The data set name m a level n + 1 VIER entry is lower than the high key of the level n VIER 
that the level n + 1 VIER entry points to. 

141(X'8D') First high-level VIER structure error bit is on. 

142(X'8E') I/O error indicating the VTOC index is not formatted correctly. 

143(X'8F') Either the mdex bit is zero, or the DOS bit is zero in the format-4 DSCB of a VTOC previously 
found to be an indexed VTOC. 

144(X'90') No SYSl.VTOCIX.nnn data set name in a VTOC whose fonnat-4 DSCB has the index bit on, 
indicating the VTOC has an index. 
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Code Meaning 

145(X'91 ') The data set name in a level n + 1 VIER entry is higher than the high key of the level n VIER 
that the level n + 1 VIER entry points to 

1 46(X • 92 ' ) Four or more high-level VlERs were encountered. 

147(X'93 •) Too many levels in the VTOC index. The length of the search list was exceeded. 

1 48 (X • 94 • ) VIER invalid, because offset to last section is invalid. 

149(X' 95 • ) VIER invalid, because offset to last entry in a section is invalid. 

1 SO(X ' 96 ' ) Media Manager initialization failed. 

1 5 1 (X ' 97 • ) Level-2 or higher VIER contains fewer than two entries. 

152(X'98') RECOVER=YES specified, but the static text module (ICVDCSTO) indicates recovery is not 
permitted. 

153(X'99') The format-4 DSCB on an indexed VTOC is written with either the index- or DOS-bit zeroed on 
an indexed VTOC. 

154(X*9A') A space map extends over more than 10 VTOC index records. 

155(X*9B') Data set name not found in section with key greater than or equal to the name being searched 
for. The VIER section containing the name is invalid. 

156(X'9C') Invalid VIER horizontal pointer. Horizontal pointer of VIERl points to VIER2 whose high key 
is lower than or equal to the high key of VBERl. 

157(X' 9D' ) Could not find entry m level-2 or higher VIER that matches the high key of the VIER. 

158(X'9E') Invalid section length or invalid number of sections in a VIER header. 

1 59(X ' 9F • ) The first high-level VIER pointed to by the VIB has an invalid ID in the header. 
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Appendix D. Example of an OPEN InstaUation Exit Module 



The description and example of IFGOEXOB (an installation-written OPEN exit 
module that takes control during OPEN for a DCB) has been moved to Data 
Facility Product: Customization. 
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Appendix E. DFP ISMF Services 



Introduction 



This appendix describes services of the ISMF component of DFP available for 
use by external application programs that are executing as ISMF line operators 
or commands. See Data Facility Product: Customization for details related to 
creating new line operators or commands. This appendix is organized into the 
following sections: 

• DFP ISMF service descriptions 

• DFP ISMF messages available to external applications 

• DFP ISMF control blocks available to external applications 



Standard Linkage and Error Handling 



Input Register Usage 



ISMF uses registers as described below. Services are accessed by creating 
required parameter lists, loading the entry point address of the desired routine 
into register 15, then branching to the address in register 15. The first four 
letters of all entry point names identify associated control blocks. 



The following table describes registers on input to a line operator or command 
running in a DFP ISMF environment. 



Register Value on Input to Line Operator or Command 



Unused 



LPPL on input to line operator; CPPL on input to command 



2-9 Unused 



10 Points to GDRB 



11,12 Unused 



13 Points to standard save area of calling routine 

14 Address of return point in calling routine 
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Register Value on Input to Line Operator or Conunand 



15 Address of called routine 



The following table describes registers on input to a DFP ISMF service from a 
line operator or command. 



Register 


Value on Input to DFP ISMF Service 







Unused unless otherwise specified below 




1 


Points to input parameter list 




2-9 


Unused unless otherwise specified below 




10 


Points to GDRB 




11,12 


Unused unless otherwise specified below 




13 


Points to standard save area of calling routine 




14 


Address of return point in calling routine 




15 


Address of called routine 





Output Register Usage 



The following table describes registers on output from a DFP ISMF service to a 
line operator or command, or on output from a line operator or command to 
ISMF. 



Register Value on Output from DFP ISMF Service, Line Operator, 
or Conunand 

0-14 Unused unless otherwise specified below 

15 Return code 



Building Parameter Lists and Finding Control Blocks 

Parameter lists must be constructed in one of two ways: 

• The list consists of 3 1-bit pointers to required inputs, with the last entry of 
the list marked by having the high-order bit set to 1. 

• The list consists of a set of flag bits followed by 3 1-bit pointers. The flag 
bits indicate which parameters are present and which are omitted. 

Most control blocks are pointed to by fields in other control blocks. To find a 
control block, use the entry point name provided and find the control block 
whose name is equal to the first four letters of the given entry point name. The 
rest of the given entry point name identifies the field in the control block 
(identified by the first four letters) that contains the entry point. 
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Error Loggiiig 



For example, the control block ARVT identifies the field GDRBARVT as its 
entry point. Following the rules stated above, GDRB is the control block that 
contains the entry point address for the ARVT in the field labeled GDRBARVT 
(offset 8). The GDRB lists register 10 as its entry point; therefore, you find the 
entry point for the ARVT in the field at location GDRB + 8. Some fields in 
parameter lists refer to fields in control blocks; you may locate these fields in a 
similar manner. 



If an error occurs, all services write information to the ERNT (see service 
descriptions for details). Typical error logging includes the failing module name, 
return code, reason code, and other diagnostic information. DFP ISMF creates a 
chain of ERNT control blocks to log errors. The ERTBCURR field in the 
ERTB always points to the current ERNT. 
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DFP ISMF Services 



DGTCDTOl Decrement Use Count 



Function: DGTCDTOl decrements the use count of modules loaded by 
DGTCLDOl. 

Entry Point Address: SRVTDTOl 

Input: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex Parameter 

3 1-bit pointer to an 8-byte character variable set to the name of the 

module to be deleted 

Output: DGTCDTOl provides a return code, as follows. 

Regbter states: R15 contains a return code, and the ERNT is updated as 
described below. 



Return Code ERNT Field 
Name 







ERNTMODN 

ERNTPD 

ERNTPROC 

ERNTRC 

ERNTRSNC 
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DGTCDVOl Data Set Name Syntax Verification 



Function: DGTCDVOl verifies data set name syntax. If the variable pointed to 
by the last parameter in the following list is set to a blank (X'40'), unquoted 
input data set names are returned unquoted with the TSO prefix appended. 
Quoted input data set names are returned unchanged, but without quotation 
marks. 

Entry Point Address: SRVTDVOl 

JnjMit: Rl points to the parameter Ust described below. 

Parameter list 



Offset 
Hex (Dec) 


Parameter 





31 -bit pointer to a 60-byte character variable set to input data set 
name 


4 


31 -bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) full data set name 


8 


31 -bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) partial data set name 


C(12) 


31 -bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) member of partitioned data set 


10(16) 


31 -bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) relative generation reference data set 


14 (20) 


31 -bit pointer to a 60-byte character variable to be set to output 
data set name. 


18 (24) 


31 -bit pointer to a 1-byte character variable set to Y (allow) or 
blank (disallow) the following: TSO prefix should not be 
appended to data set name and data set name must be unquoted 



Output: The output data set name is updated. 

Register states: R15 contains a return code, and the ERNT fields listed below 
are updated. 



Return 


ERNT Field 


Code 


Name 





8 


ERNTLMSG 




ERNTMODN 




ERNTPROC 




ERNTRSNC 




ERNTRC 




ERNTSMSG 
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Return 


ERNT Field 


Code 


Name 


12 


ERNTLMSG 




ERNTMODN 




ERNTPROC 




ERNTRSNG 




ERNTRC 




ERNTSERV 




ERNTSMSG 
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DGTCEPOl Free Storage and Exit 



Function: DGTCEPOl frees storage gotten by DGTCPROl and exits to the 
caUer of the routine that called DGTCEPOl. 

Entry Point Address: SRVTEPOl 

Input: Rl points to the parameter list described below. 

Parameter list 



Register 


Parameter 





31 -bit pointer to a 15 -bit variable set to the ISMF exit return code 


1 


31 -bit pointer to an 8-byte character variable set to the name of 
the calling module 


2 


31 -bit pointer to storage to be freed 



Output: DGTCEPOl provides a return code, as follows. 

Register states: R15 contains a return code, and the following ERNT fields are 
updated. RO contains a pointer to the return code to be passed back to the 
original caller (caller of the caller of DGTCEPOl). Rl contains a pointer to the 
size of the invoking module's automatic data area. 



Return 


ERNT Field 


Code 


Name 





12 






ERNTMODN 




ERNTPROC 




ERNTRSNC 




ERNTRC 
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DGTCFMOl Free Memory 



Function: DGTCFMOl frees storage acquired through DGTCGMOl . 
Entry Point Address: SRVTFMOl 
Ii^ut: Rl points to the parameter list described below. 
Parameter list 

Offset 

Hex (Decimal) Parameter 

3 1-bit pointer to a 4-byte character variable set to the storage 

identifier of the caller 

4 3 1-bit pointer to a 3 1-bit pointer to the address of the area to be 

freed 



Output: DGTCFMOl provides a return code, as follows. 

Registar states: RIS contains a return code and the following ERNT fields are 
updated. 



Return 


ERNT Field 


Code 


Name 





12 






ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRSNC 




ERNTRC 




ERNTSERV 
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DGTCGMOl Get Storage 



Function: DGTCGMOl gets storage (which is freed by DGTCFMOl). If the 
first attempt to obtain storage fails, DGTCGMOl deletes modules (loaded by 
DGTCLDOl) whose use count is zero and will retry the operation. 

Entry Point Address: SRVTGMOl 

Input: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex (Decimal) Parameter 

3 1-bit pointer to a 3 1-bit variable set to number of storage 

bytes to be obtained 

4 3 1-bit pointer to a S-bjrte character variable set to BLANK or 

ZERO, specifying whether to initialize obtained storage to 
zeros or blanks 

8 31 -bit pointer to a 4-byte character variable set to the storage 

identifier of the obtained storage 

C (12) 3 1-bit pointer to a 5-byte character variable set to BELOW or 

ANY, specifying storage to be obtained from BELOW the 16 
megabyte boundary or from ANY location 

10 (16) 31 -bit pointer to a 5-byte character variable set to DBLWD or 

PAGE, specifying storage to be aligned on a doubleword or 
page boundary 

14 (20) 3 1-bit pointer to a 3 1-bit variable to be set to the address of the 

obtained storage 

Output: The last field of the parameter list {address of obtained storage) is 
updated to contain a pointer to the new storage. 

Register states: RIS contains a return code and the following ERNT fields are 
updated. 



Return 


ERNT Field 


Code 


Name 





12 


ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRSNC 




ERNTRC 




ERNTSERV 
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DGTCLDOl Load a Module 



Function: DGTCLDOl loads a requested module into storage; if the module is 
already loaded, DGTCLDOl increments the module's use count. 

Entry Point Address: SRVTLDOl 

/n/w/.* Register states: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex (Decimal) Parameter 

3 1-bit pointer to an 8-b5rte character variable set to the name of 

the requested module 

4 3 1-bit pointer to a 3 1-bit variable that will be updated to 

contain the entry point address of the loaded module 

Output: DGTCLDOl provides a return code, as follows, and the variable 
pointed to by the load entry point address field of the parameter list is updated. 

Roister states: RIS contains a return code and the ERNT is updated as 
described below. 



Return 


ERNT Field 


Code 


Name 





12 






ERNTMODN 




ERNTPROC 




ERNTRC 




ERNTRSNC 




SRVC 




ERNTPD 
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DGTCLGOl Place Information in the ISPF Log 



Function: DGTCLGOl creates log entries based on infonnation from the 
current ERNT, the current IMNT, or the log buffer. If the first parameter in the 
following list is set to ERROR, the ERNT is used as the information source; if 
the first parameter is set to DVITT, the IMNT is used as the source, and if the 
first parameter is set to STATUS, the log buffer is used as the source. 

Enity Point Address: SRVTLGOl 

Input: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex Parameter 

3 1-bit pointer to a 6-byte character variable set to the type of 

entry to be generated. Possible entries: ERROR, STATUS, IMTT 

4 31 -bit pointer to an 8-byte character variable set to the address 

of a message to be written to the log if tjipe was set to STATUS, 
set to blanks otherwise 

8 3 1-bit pointer to a 3 1-bit variable set to zeros 

Out/Hit: DGTCLGOl provides a return code, as follows. 

Register states: R15 contains a return code and the following ERNT fields are 
updated. 



Return 


ERNT Field 


Code 


Name 





12 


ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRSNC 




ERNTRC 




ERNTSERV 
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DGTCPROl Obtain Automatic Data Area 



Function: If tracing is oh, DGTCPROl gets a module's automatic data area, 
adds an entry to the Inter-Module Trace Table, and writes an entry to the ISMF 
log. 

Entry Point Address: SRVTPROl 

Inpiri: Rl points to the parameter list described below. 

Paran^erlist 



Register 


Parameter 





31 -bit pointer to a 31 -bit variable set to the amount of storage 
needed 


1 


31 -bit pointer to an 8-byte character variable set to calling module 
name 



Output: DGTEPROl provides a return code, as follows. 

Register states: RIS contains a return code, Rl contains the address of the new 
storage, and the following ERNT fields are updated. 



Return 
Code 


ERNT Field 
Name 





12 


ERNTMODN 
ERNIPROC 
ERNIRSNC 
ERNIRC 
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DGTCWOl Volume Serial Number Syntax Verification 



Function: DGTCWOl verifies volume serial number syntax. DGTCWOl does 
not support quoted volume serial numbers. 

Entry Point Address: SRVTWOl 

Ii^ut: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex Parameter 

31 -bit pointer to a 6-byte character variable set to the volume 

serial number to be checked 

4 31 -bit pointer to a 1-byte character variable set to Y (allow) or 

blank (disallow) full volume serial number 

8 3 1-bit pointer to a 1-byte character variable set to Y (allow) or 

blank (disallow) partial volume serial number 

Output: DGTCWOl provides a return code, as follows. 

Register states: RIS contains a return code and the following ERNT fields are 
updated. 



Return 


ERNT Field 


Code 


Name 





8 


ERNTLMSG 




ERNTMODN 




ERNTPROC 




ERNTRSNC 




ERNTRC 




ERNTSMSG 
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DGTCWOOl Word Finder 



FwKtion: DGTCWOOl scans a specified section of storage for a character 
string delimited by blanks. 

Entry Point Address: SRVTWOOl 

Ii^ui: Rl points to the parameter list described below. 

Parmnetar list 

Offset 

Hex (Decimal) Parameter 

3 1-bit pointer to a 3 1-bit variable set to the start address of 

storage to be scanned 

4 3 1-bit pointer to a 3 1-bit variable set to the end address of 

storage to be scanned 

8 3 1-bit pointer to a 3 1-bit variable that will contain the address 

of the first word found 

C ( 12) 3 1-bit pointer to a 3 1-bit variable that will contain the size of 

the first word found 

Output: The word and size fields of the parameter list will be updated. 

Reffster states: R15 contains a return code and the following ERNT fields are 
updated. 



Retwn 
Code 


ERNT Field 
Name 





12 


ERNTMODN 
ERNIPROC 
ERNTRSNC 
ERNIRC 
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DGTFARFl Find an Entry in the Data Set List Array 



Function: DGTFARFl finds information in the data set list array and moves the 
current row pointer to the new position. 

Entry Point Address: ARVTFIND 

Ii^ut: Register states: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex Parameter 

31 -bit pointer to a 32-bit parameter set to X • 3 ' , indicating which 

parameters are present 

4 3 1-bit pointer to the SELB 

8 3 1-bit pointer to a 3-byte character variable set to YES, specifying 

retrieve information, or NO, specifying find information only. 

Output If the retrieve information field of the parameter list specified YES, 
DGTFARFl updates variables addressed by the DABVAR fields. DGTFARFl 
provides a return code, as follows: 

Register states: R15 contains a return code and the ERNT is updated as 
described below. 



Return 


ERNT Field 


Code 


Name 





8 


ERNTLMSG 




ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRC 




ERNTRSNC 




ERNTSERV 




ERNTSMSG 


12 


ERNTLMSG 




ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRC 




ERNTRSNC 




ERNTSERV 




ERNTSMSG 
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DGTFARPl Position Current Row Pointer at Top of List 



Function: DGTFARPl positions the current row pointer at the top of the data 
set list array. The data set list array is an internal representation of data set 
names. 

Entry Point Address: ARVTPOS 

Input: Register states: Rl points to the parameter list described below. 

Parameto' list 



Offset 

Hex (Decimal) 


Parameter 





31 -bit pointer to a 32-bit parameter set to X' 19', indicating 
which parameters are present 


4 


31 -bit pointer set to the value of CPPLARNM 


8 


31 -bit pointer to a 31 -bit variable set to zeros 


C(12) 


31 -bit pointer to a 31 -bit variable set to zeros 


10(16) 


31 -bit pointer to a 3 -byte character variable set to 'TOP' 


14 (20) 


31 -bit pointer to a 2-byte character variable set to 'NO' 


18 (24) 


31 -bit pointer to a 31 -bit variable set to zeros 


IC (28) 


31 -bit pointer to a 31 -bit variable set to zeros 



Output:: DGTFARPl provides a return code, as follows. 

Register states: R15 contains a return code and the ERNT is updated as 
described below. 



Return 


ERNT Field 


Code 


Name 





8 


ERNTLMSG 




ERNTMODN 




ERNTPROC 




ERNTRC 




ERNTRSNC 




ERNTSERV 




ERNTSMSG 


12 


ERNTLMSG 




ERNTMODN 




ERNTPROC 




ERNTRC 




ERNTRSNC 




ERNTSERV 




ERNTSMSG 
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DGTFARSl Obtain Count of Data Sets 



Function: DGTFARSl obtains the total number of displayable data sets from 
the data set list array. 

Entry Point Address: ARVTSTAT 

Input: Register states: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex (Decimal) Parameter 

3 1-bit pointer to a 32-bit string set to X'F* , indicating which 

parameters are present 

4 3 1-bit pointer set to the value in CPPLARNM 

8 31 -bit pointer to a 6-byte character variable set to ' RETURN • 

C ( 1 2) 31 -bit pointer to a 7-byte character variable set to • DISPROW ' 

10 (16) 31-bit pointer to a 31-bit variable where DGTFARSl will pass 

back count of displayable data sets 

ID (20) 31 -bit pointer to a 31 -bit variable set to zeros 

Output: DGTFARSl updates the variable pointed to by the count field, and 
provides a return code as follows: 

Register states: R15 contains a return code and the ERNT is updated as 
described below. 



Retun 


ERNT Field 


Code 


Name 





8 


ERNTLMSG 




ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRC 




ERNTRSNC 




ERNTSERV 




ERNTSMSG 


12 


ERNTLMSG 




ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRC 




ERNTRSNC 




ERNTSERV 




ERNTSMSG 
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DGTFARUl Update Data Set List Array 



Function: DGTFARUl updates columns for the entry in the data set list array 
pointed to by the current row pointer. 

Entry Point Address: ARVTUPDT 

Ii^tt: Register states: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex (Decimal) Parameter 

3 1-bit pointer to a 32-bit parameter set to X* 3 ' , indicating which 

parameters are present 

4 31 -bit pomter set to the value of CPPLARNM 

8 3 1-bit pomter to the DABL 

C ( 1 2) 31 -bit pointer to a 3 1 -bit variable set to zeros 

Output: DGTFARUl updates the data set list array and provides a return code 
as follows: 

Regbter states: RIS contains a return code and the ERNT is updated as 
described below. 



Return 


ERNT Field 


Code 


Name 





8 


ERNTLMSG 




ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRC 




ERNTRSNC 




ERNTSERV 




ERNTSMSG 


12 


ERNTLMSG 




ERNTMODN 




ERNTPD 




ERNTPROC 




ERNTRC 




ERNTRSNC 




ERNTSERV 




ERNTSMSG 
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DGTFCTCK Verify Commands 



Function: DGTFCTCK checks the validity of commands in the CTAP. 
Commands in the CTAP must be enabled by DGTFCTSE before use. 

Entry Point Address: CTVTCTCK 

Input: Rl points to the parameter list described below. 

Parameter list 

Offset 

Hex (Decimal) Parameter 

3 1-bit pointer to a 3 1-bit pointer to the command Une field 

4 3 1-bit pointer to a 3 1-bit variable set to the command Une length 

8 31 -bit pointer to a 1-byte character variable set to a blank 
(X'40') . 

C (12) 31 -bit pointer to an 8-byte character variable where 

DGTFCTCK will pass back the name of the load module which 
processes the named command 

10 (16) 31 -bit pointer to an 8-byte character variable where 

DGTFCTCK will pass back the name of the command 

Output: DGFFCTCK updates the command routine (load module) and command 
name fields, and provides a return code as follows: 

Register states: R15 contains a return code and the following ERNT fields are 
updated. 



Return 
Code 


ERNT Field 
Name 





8 


ERNTLMSG 
ERNTRSNC 
ERNTSMSG 


12 


ERNTLMSG 
ERNTRSNC 
ERNTSMSG 



Appendix E. DFP ISMF Services 325 



DGTFCTPR Process commands 



Function: DGTFCTPR gives control to the load module that processes input 
commands. You must create the CTPL in order to use DGTFCTPR. 

Entry Point Address: CTVTCTPR 

Input: Rl points to the parameter Ust described below. 

Parameter list 

Offset 

Hex Parameter 

31 -bit pomter to the CTPL 

Output: DGTFCTPR provides a return code, as follows. 

Roister states: RIS contains a return code and the following ERNT fields are 
updated. 



Return 
Code 


ERNT Field 
Name 





8 


ERNTLMSG 
ERNIRSNC 
ERNTSMSG 


12 


ERNTLMSG 
ERNIRSNC 
ERNISMSG 
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DGTFCTSE Enable VaUd Commands 



Function: DGTFCTSE, by updating the CTAP, enables all commands listed in 
the CTFU and disables all others, others by updating the CTAP. You must 
create the CTFU to use DGTFCTSE. 

Entry Point Address: CTVTCSE 

Iiqmt: Register states: Rl points to the parameter list described below. 

Pananeter list 

Offset 

Hex Parameter 

31 -bit pointer to the CTFU 

Output: DGTFCTSE provides a return code, as follows. 

Regktar sUdes: R15 contains a return code and the ERNT is updated as 
described below. 



Return 
Code 


ERNT Field 
Name 





8 


ERNTLMSG 
ERNIRSNC 
ERNTSMSG 


12 


ERNTLMSG 
ERNIRSNC 
ERNTSMSG 
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DGTFFOEl Obtain Input Information From the Screen Area Image 



Function: DGTFFOEl obtains input information from the specified entry in the 
list of data sets displayed in the screen area image. 

Entry Point Address: FOVTGTVL 

Input: Register states: Rl points to the parameter list described below. 

Parametar lust 



Offset 

Hex (Decimal) 


Parameter 





31-bit pointer to a 32-bit parameter set to X'F', indicating which 
parameters are present 


4 


31 -bit variable set to the value of LPPLFOAD 


8 


31 -bit variable set to the value of LPPLARAD 


C(12) 


31 -bit pointer to the address of LPPLENT 


10(16) 


3 1 -bit pointer to the D ABL 


14 (20) 


31 -bit pointer to a 31 -bit variable set to zeros. 


18 (24) 


31 -bit pointer to a 31 -bit variable set to zeros. 


IC (28) 


31 -bit pointer to a 31 -bit variable set to zeros. 



Output: DGTFFOEl updates the variables addressed by the DABVAR, and 
provides a return code as follows: 

Register states: R15 contains a return code and the ERNT is updated as 
described below. 



Return 
Code 


ERNT Field 
Name 





12 


ERNTMODN 
ERNTPROC 
ERNTRC 
ERNTRSNC 
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DGTFFOLl Refresh the Screen Image Area From the Data Set list 
Array 

Function: DGTFFOLl uses the data set list array to refresh the screen image 
area. 

Entry Point Addnss: FOVTLOAD 

Input: Register states: Rl points to the parameter list described below. 

Pananeter list 

Offset 

Hex Parameter 

3 1-bit pointer to a 32-bit parameter set to X' 3 ' , indicating which 

parameters are present 

4 31 -bit pointer set to the value of CPPLFONM 

8 3 1-bit pointer set to the value of CPPLARNM 

Output: DGTFFOLl provides a return code, as follows. 

Register states: R15 contains a return code and the ERNT is updated as 
described below. 



Return 


ERNT Field 


Code 


Name 





8 


ERNTMODN 




ERNTPROC 




ERNTRC 




ERNTRSNC 


12 


ERNTMODN 




ERNTPROC 




ERNTRC 




ERNTRSNC 



Appendix E. DPP ISMF Services 329 



DFP Common Services 



IGBDISOO Call Device Information Services for UCB Address 

Function: IGBDISOO returns the address of the first UCB found for the generic 
device type passed as mput Whenever IGBDISOO provides return code 8, you 
must re-call the function, passing the same parameter list you used on the first 
call. Do not initialize any fields as indicated in the following instructions for 
making the first call to the service; make the second call with the parameter 
exactly as it is returned from the first call. The second call to IGBDISOO frees 
storage acquired by the function on the first call. 

Entry Point Address: CVTEXT2 + 12; resulting address + 36. 

Ii^ut: RO contains zeros and Rl contains a pointer to a pointer to the 
parameter list described below. You must create the parameter list described 
below; it must be 60 bytes long and you must fill in only the indicated fields; you 
must set the rest to zeros. You must also create a H-byte problem determination 
area and a 25-byte return area, both initialized to zeros. 

Pananeto' list 



Offset 

Hex (Decimal) 


Parameter 





X'OOSCOIOO' 


6 


X'lO' 


7 


X'OO' (first call); X'02' (second call) 


8 


31 -bit pointer to return area 


C(12) 


31 -bit variable set to the return area length 


10 (16) 


31 -bit pointer to the problem determination area 


14 (20) 


31 -bit variable set to the problem determination area length 


28 (40) 


8-byte character variable set to the generic device type name 



Output: IGBDISOO provides the UCB address in the return area + 20, and, if an 
error occurred, updates the problem determination area. It also provides a return 
code as follows. 

Register sUttes: R15 contains one of the following hex return codes: 0, 8 
(successful), 10, IC, 20, 3C (unsuccessful). See DFP Diagnosis for a 
description of the problem determination area and details about the valid return 
codes and reason codes. 
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DFP ISMF Messages Available to External Applications 



The following messages are in the data set 'SYSl.DGTMLIB', with member 
names identified by the full message name minus the last character of the 
message name. For example, message DGTUV005 is in 
'SYSl.DGTMLIB(DGTUVOO)' Likewise, message DGTUV016 is in 
'SYSl.DGTMLIB(DGTUVOl)' and so on. Each member contains 10 messages, 
numbered through 9. 



DGTUV005 'ENTER Y OR N' .HELP= DGTMUV05 .ALARM= YES 

'ENTER Y OR N AT THE CURSOR POSITION 

DGTUV006 'INVALID COMBINATION' .HELP= DGTMUV06 .ALARM= YES 
'IF MAXIMUM NUMBER OF RETRIES=0 THEN SECONDS BETWEEN RETRIES MUST BE 

DGTUV007 'INVALID COMBINATION' .HELP= DGTMUV07 .ALARM= YES 
'IF SECONDS BETWEEN RETRIES=0 THEN MAXIMUM NUMBER OF RETRIES MUST BE 

DGTUV016 'MUST BE BLANK' .HELP= DGTMUV16 .ALARM= YES 

'AMOUNT OF I/O BUFFERING MUST NOT BE SPECIFIED IF DUMP IN COMPRESSED FORM = Y 

DGTUV021 'SPECIFY ONE OR MORE' .HELP= DGTMUV21 .ALARM= YES 
'YOU MUST SPECIFY ONE OR MORE OF THE FIELDS BELOW 

DGTUV024 'ISMF INTERNAL ERROR' .HELP= DGTMUV24 .ALARM= YES 
'ISMF INTERNAL PROCESSING ERROR 

DGTUV031 'ENTER 1 OR 2 ' .HELP= DGTMUV31 .ALARM= YES 

'ENTER 1 OR 2 AT THE CURSOR POSITION 

DGTUV032 'RESET MUST EQUAL N' .HELP= DGTMUV32 .ALARM= YES 
'RESET = Y IS INVALID IF ACCESS SOURCE DATA SET IN SHARED MODE = Y 

DGTUV037 ' ' .ALARM= NO 

' 8L0GBJBNM(&L0GBJBN0) SUBMITTED 

DGTUV038 ' ' .ALARM= NO 

' &LOGBJBNM PLACED IN SLOGBJBDS 

DGTUV040 ' ' .ALARM= NO 

' &LOGBJBNM ADDED TO &LOGBJBDS 

DGTUV045 'SCURLIOP FAILED' .HELP= DGTMUV45 .ALARM= YES 

' &CURLIOP LINE OPERATOR FAILED DUE TO AN UNEXPECTED ISMF INTERNAL ERROR 

DGTUV046 ' &CURCMD FAILED' .HELP= DGTMUV46 .ALARM= YES 

' 8CURCMD COMMAND FAILED DUE TO AN UNEXPECTED ISMF INTERNAL ERROR 

DGTUV048 'COMMAND FAILED' .HELP= DGTMUV48 .ALARM= YES 

'EITHER THE COMMAND FAILED OR AN UNEXPECTED INTERNAL ISMF ERROR OCCURRED 

DGTUV049 'MISSING VOLSER' .HELP= DGTMUV49 .ALARM= YES 

'AT LEAST ONE VOLUME SERIAL NUMBER MUST BE SPECIFIED 

DGTUV050 'MISSING UNIT TYPE' .HELP= DGTMUV50 .ALARM= YES 
'UNIT TYPE MUST BE SPECIFIED FOR VOLUME SERIAL (S) 

Figure 46 (Part 1 of 3). DFP ISMF Messages Available to External Applications 
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DGTUV051 'SCURCMD INVALID' .HELP= DGTMUV5T .ALARM= YES 

'gCURCMD IS ONLY VALID WHEN ENTERED FROM THE LIST PANEL 

DGTUV052 'UNABLE TO FIND VOLSER' .HELP= DGTMUV52 .ALARM= YES 
•THE ACTUAL VOLUME SERIAL FOR THE INDIRECT VOLSER COULD NOT BE FOUND 

DGTUV053 'UPDATE OF LIST FAILED' .HELP= DGTMUV53 .ALARM= YES 
'BACKGROUND JOB SUCCESSFULLY CREATED BUT UPDATE OF LIST FAILED 

DGTUV054 'INVALID STATUS' .HELP= DGTMUV54 .ALARM= YES 

'IF NO OUTPUT VOLUMES OR UNIT SPECIFIED, STATUS MUST BE OLD 

DGTUV055 'MISSING DEVICE TYPE' .HELP= DGTMUV55 .ALARM= YES 

'WHEN STATUS OF DATA SET IS NEW, AT LEAST A VALUE FOR UNIT MUST BE SPECIFIED 

DGTUV056 'MUST BE 3 OR BLANK' .HELP= DGTMUV56 .ALARM= YES 
'WHEN REPLACE IF DUPLICATE REQUESTED, DO NOT RENAME DATA SET 

DGTUV057 'DUPLICATE DATA SET NAME' .HELP= DGTMUV57 .ALARM= YES 
'DUPLICATE DATA SET NAME INVALID FOR LIST COMMAND 

DGTUV062 'PANEL PRIMING FAILED' .HELP= DGTMUV62 .ALARM= YES 
•UNABLE TO RETRIEVE SAVED PANEL VALUES - LAST-USE MODE IGNORED 

DGTUV063 'PANEL PRIMING FAILED' .HELP= DGTMUV63 .ALARM= YES 
•UNABLE TO RETRIEVE SAVED PANEL VALUES 

DGTUV067 'gCURLIOP INVALID' .HELP= DGTMUV67 .ALARM= YES 

' &CURLIOP INVALID FOR A DFHSM MIGRATED DATA SET 

DGTUV068 'MIGRATED DATASET INVALID' .HELP= DGTMUV68 .ALARM= YES 
'DFHSM MIGRATED DATA SETS ARE INVALID FOR THE gCURCMD LIST COMMAND 

DGTUV069 'TOO MANY VOLSERS ' .HELP= DGTMUV69 .ALARM= YES 

'MORE THAN 255 DIFFERENT VOLSERS IN THE DATA SET LIST 

DGTUV070 'gCURCMD JOB CREATED' .HELP= DGTMUV70 .ALARM= NO 
'BACKGROUND JOB SUCCESSFULLY CREATED FOR THE gCURCMD COMMAND 

DGTUV071 'INVALID VOLSER' .HELP= DGTMUV71 .ALARM= YES 

•VALID VOLSER REQUIRED TO PERFORM THE REQUESTED FUNCTION 

DGTUV072 'ENTER REQUIRED FIELD' .HELP= DGTMUV72 .ALARM= YES 
'WHEN SPACE UNITS IS BLKS, A VALUE FOR BLOCKSIZE IS REQUIRED 

DGTUV073 'ENTER REQUIRED FIELD' .HELP= DGTMUV73 .ALARM= YES 
'WHEN STATUS IS NEW, SPACE QUANTITIES ARE REQUIRED 

DGTUV080 'INVALID DATA SET NAME' .HELP= DGTMUV80 .ALARM= YES 

'THE LINE OPERATOR FAILED BECAUSE IT WAS ISSUED AGAINST A BLANK DATA SET NAME 

DGTUV082 'BLANK NAME INVALID' .HELP= DGTMUV82 .ALARM= YES 
'BLANK DATA SET NAMES ARE INVALID FOR LIST COMMANDS 

DGTUV083 'INVALID DEVICE TYPE' .HELP= DGTMUV83 .ALARM= YES 
'VALID DEVICE TYPE REQUIRED TO PERFORM THE REQUESTED FUNCTION 

Figure 46 (Part 2 of 3). DFP ISMF Messages Available to External Applicati<His 
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DFQHA001 'RANGE TO 999' .HELt>= DFQHA001 .ALARM= YES 

•specify a number in the range of TO 999 

DFQHA002 'RANGE TO 1 3 ' .HELP= DFQHA002 .ALARM= YES 

•SPECIFY A NUMBER IN THE RANGE OF TO 1 3 

DFQHA003 'MUTUALLY EXCLUSIVE FIELDS' .HELP= DFQHA003 .ALARM= YES 
•CANNOT SPECIFY NO. OF DAYS OR NO. OF BACKUP VERSIONS FOR SYSTEM DEFAULT 

DFQHR001 'INVALID VOLSER' .HELP= DFQHR001 .ALARM= YES 

•CONTAINS INVALID CHARACTERS 

DFQHR002 'ENTER REQUIRED INPUT' .HELP= DFQHR002 .ALARM= YES 
•VOLUME AND DEVICE TYPE MUST BOTH BE SPECIFIED, OR SPECIFY NEITHER 

DFQHR003 'INVALID DEVICE TYPE' .HELP= DFQHR003 .ALARM= YES 

•THE DEVICE TYPE MUST BE 3330, 3330-1, 3330v, 3350, 3375, or 3380 

DFQHC001 'RANGE TO 12' .HELP= DFQHC001 .ALARM= YES 

'SPECIFY A NUMBER IN THE RANGE OF TO 1 2 

DFQHM001 'INVALID HMIGRATE COMMAND .HELP= DFQHM001 .ALARM= YES 
'CANNOT BE MIGRATED TO LEVEL- 1 FOR A TAPE ONLY MIGRATE SYSTEM 

DFQHM002 'INVALID HMIGRATE COMMAND .HELP= DFQHM002 .ALARM= YES 
'HMIGRATE CANNOT BE ISSUED FOR A LEVEL-2 TO A LEVEL- 1 

DFQHM003 'INVALID HMIGRATE COMMAND .HELP= DFQHM003 .ALARM= YES 
•HMIGRATE CANNOT BE ISSUED FOR A LEVEL- 1 TO A LEVEL- 1 

DFQHD001 'INVALID HBDELETE COMMAND' .HELP= DFQHD001 .ALARM= YES 
•THERE ARE NO BACKUP VERSIONS TO DELETE 

DFQCN001 'INVALID CONDENSE COMMAND' .HELP= DFQCN001 .ALARM= YES 
•CONDENSE CANNOT BE ISSUED FOR A MIGRATED DATA SET 

DFQCN002 'INVALID CONDENSE COMMAND' .HELP= DFQCN002 .ALARM= YES 
•CONDENSE CANNOT BE ISSUED FOR A TAPE ONLY MIGRATE SYSTEM 

DFQCN003 'INVALID CONDENSE COMMAND' .HELP= DFQCN003 .ALARM= YES 
•CONDENSE CAN ONLY BE ISSUED FOR A DATA SET WITH DSORG OF PS OR PO 

DFQCN004 'DSORG CANNOT BE OBTAINED' .HELP= DFQCN004 .ALARM= YES 
•ERROR DURING THE OBTAIN OF THE FORMAT 1 DSCB TO DETERMINE DSORG 



Figure 46 (Part 3 of 3). DFP ISMF Messages Available to External An>lications 
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The following messages are not displayed on a line operator entry panel, but are 
written in the ISPF log as problem determination aids. 



DFQLP001 'READ FOR DFHSM RECORD FAILED' .HELP= DFQLP001 
'THE READ FOR THE DFHSM CDS RECORD FAILED, SVC ERROR 



DFQLP002 'LINE OPERATOR FAILED' 
•LINE OPERATOR FAILED 



.HELP= DFQLP002 



,ALARM= YES 



,ALARM= YES 



DFQLP003 'READ FOR DFHSM RECORD FAILED' .HELP= DFQLP003 
'THE READ FOR THE DFHSM CDS RECORD FAILED, DFHSM ERROR 

DFQLP004 'SUCCESSFUL SUBMISSION' .HELP= DFQLP004 
'lineop LINE OPERATOR SUBMITTED SUCCESSFULLY 



.ALARM= YES 



.ALARM= YES 



Figure 47. DFP ISMF Problem Determination Messages 
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DFP ISMF Control Blocks AvaUable to External Applications 



This section describes DFP ISMF control blocks available for use by external 
applications. Most control blocks are pointed to by fields in other control 
blocks. To find a control block, use the entry point name provided and find the 
control block whose name is equal to the first four letters of the given entry 
point name. The rest of the given entry point name identifies the field in the 
control block (identified by the first four letters) which contains the entry point. 

For example, the control block ARVT identifies the field GDRBARVT as its 
entry point. Following the rules stated above, GDRB is the control block that 
contains the entry point address for the ARVT in the field labeled GDRBARVT 
(offset 8). The GDRB lists register 10 as its entry point; therefore, you find the 
entry point for the ARVT in the field at location GDRB + 8. 



ARVT 

Entry Point: GDRBARVT 



ARVT 
Offsets 



Type, 



Length Name 



Description 



ARRAY SERVICE VECTOR TABLE (ARVT) 







4 

6 

8 

12 

16 

20 

24 

28 

32 

36 

40 

44 

48 

52 

56 



(0 

(0 

(4 

(6 

(8 

(C 

(10 

(14 

(18 

(1C 

(20 

(24 

(28 

(2C 

(30 

(34 

(38 



CHARACTER 

CHARACTER 

FIXED 

FIXED 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

CHARACTER 



56 ARVT 

4 ARVTVID 

2 ARVTLEN 

2 ARVTUCNT 

4 ARVTBEG 

4 ARVTDONE 

4 ARVTADD 

4 ARVTCRET 

4 ARVTDELR 

4 ARVTENDM 

4 ARVTFIND 

4 ARVTPOS 

4 ARVTSORT 

4 ARVTSTAT 

4 ARVTUPDT 

4 ARVTTBLS 
ARVTEND 



VISUAL ID: 'ARVT' 
LENGTH OF ARVT 
USE COUNT 

ADDRESS OF ARBEGIN MODULE 
ADDRESS OF ARDONE MODULE 
ADDRESS OF ARADD MODULE 
ADDR. OF ARCREATE MODULE 
ADDR. OF ARDELROW MODULE 
ADDRESS OF AREND MODULE 
ADDRESS OF ARFIND MODULE 
ADDRESS OF ARPOSIT MODULE 
ADDRESS OF ARSORT MODULE 
ADDRESS OF ARSTATS MODULE 
ADDR. OF ARUPDATE MODULE 
ADDR. OF ROWID CNTRL BLK 
END OF ARVT 



CLCB 

Entry Point: LPPLCLCB/CPPLCLCB (LPPLCLCB for line operators, CPPLCLCB for commands). 
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CLCB 
Offsets 



Type Length Naume 
COMMAND/LINE OPERATOR CONTROL BLOCK 



Description 



(0) CHARACTER ♦ CLCB 

(0) CHARACTER 4 CLCBVID 

4 (4) FIXED 2 CLCBLEN 

6 (6) BITSTRING 1 CLCBFLG1 

7 (7) BITSTRING 1 CLCBFLG2 

8 (8) ADDRESS 4 CLCBNEXT 
12 (C) ADDRESS 4 CLCBPREV 
16 (10) CHARACTER * CLCBENT 



VISUAL ID: 'CLCB' 

LENGTH OF CLCB 

FLAG FIELD 

FLAG FIELD 

ADDR OF ENXT CLCB 

ADDR. PREV CLCB 

CLCB ENTRY 



CONH 



Entry Poini: SELBCONH 

If you are using DGTFARFl, the CONHCNT field must be a 15-bit variable set to the number of DABs 
whose column values are used to search the data set list array. The CONHCONE must be a 31 -bit pointer 
to each CONE associated with the CONH. 



CONH 
Offsets 



Type Length Name Description 

CONDITIONAL CONTROL BLOCK HEADER (CONH) 



(0) CHARACTER 

(0) CHARACTER 

(0) CHARACTER 

4 (4) FIXED 

6 (6) FIXED 

8 (8) ADDRESS 



* CONH 

8 CONHMAIN 

4 CONHVID 

2 CONHLEN 

2 CONHCNT 

4 CONHCONE (*) 



VISUAL ID: 'CONH' 
LENGTH OF CONH 
NUMBER OF ENTRIES 
CONE ADDRESSES 



CONH 



Entry Point: CONHCONE 



If you are using DGTFARFl, you must set the CONENAME to a column name as specified in the DAB 
associated with the CONE; you must set the CONECOND to either *EQ' or 'NE', used when comparing 
the value in the variable pointed to by the DABVAR in the DAB associated with this CONE to the column 
values in the data set list array. 



CONH 
Offsets 



Type 



Length Name 



Description 



END OF CONDITIONAL CONTROL BLOCK HEADER (CONH) CONDITIONAL 
CONTROL BLOCK ENTRY (CONE) 






(0) 


CHARACTER 


12 


CONE 





(0) 


CHARACTER 


8 


CONENAME 


8 


(8) 


CHARACTER 


2 


* 


10 


(A) 


CHARACTER 


2 


CONECOND 


12 


(C) 


CHARACTER 




CONEEND 



NAME OF COLUMN 
RESERVED UNUSED 
CONDITION 
END OF CONE 
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CPPL 



Entry Point: Rl on entry to command routine. 

Type Length Name 



CPPL 
Offsets 



Description 



COMMAND PROCESSOR PARAMETER LIST (CPPL) PASSES TO THE COMMAND 
ROUTINE 



VISUAL ID: 'CPPL' 

LENGTH OF CPPL 

FLAG FIELD 

STD INVOCATION 

INVOKE AT END OF LIST 

INVOKE AT END OF APPLICAT 

ACTIVE LINE OPERATOR? 

SET SHORT MSG DONE? 

LIST GEN'D FRM CATALOG 

SORT FLAG 

FILTER FLAG 

PANEL TYPE 

ADDRESS OF FIELD W/ ARRAY 

ADDR. OF FIELD W/ FORMAT 

ADDR. OF THE COMMAND LINE 

COMMAND LINE LENGTH 

COMMAND 

ADDR. OF COMMAND ON LINE 

ADDRESS OF COMMAND PARAM. 

ADDR. OF CURSOR CNTL BLK IT 

MAY BE EITHER THE ADDR OF PCCB 

OR LPCB 

CURRENT SCROLL AMNT ADDR. 

PREVIOUS SCROLL AMNT ADDR 

COMMAND/LINE OPERATOR CONTROL 

BLOCK CHAIN PTR 

ROWID NAME OF ROW W/ERROR 

ADDR OF CATALOG NAME 

ADDR OF DABL 

ADDR OF FILTER MOD NAME 

APPLICATION ID 

FLAG FIELD 

HSM = YES ? 

VOL = YES ? 

RESERVED, UNUSED 

RESERVED, UNUSED 

ADDR OF THE NAME OF THE 

CATALOG NAME TABLE 

ADDR OF THE LONG MSG 

RESERVED UNUSED 

END OF CPPL 






(0) 


CHARACTER 


88 


CPPL 





(0) 


CHARACTER 


4 


CPPLVID 


4 


(4) 


FIXED 


2 


CPPLLEN 


6 


(6) 


BITSTRING 


1 


CPPLFLG1 




1.. 


. .... 




CPPLSTD 




.1. 


. .... 




CPPLTEOL 




..1 


. .... 




CPPLTEOA 




. . . 


1 




CPPLLOFL 




. . . 


. 1. .. 




CPPLSMSG 




. . . 


. .1.. 




CPPLSCNM 




. . . 


. ..1. 




CPPLSORT 




. . . 


. ... 1 




CPPLFILT 


7 


(7) 


CHARACTER 


1 


CPPLPNTP 


8 


(8) 


ADDRESS 


4 


CPPLARNM 


12 


(C) 


ADDRESS 


4 


CPPLFONM 


16 


(10) 


ADDRESS 


4 


CPPLCLAD 


20 


(14) 


FIXED 


4 


CPPLCMDL 


24 


(18) 


CHARACTER 


8 


CPPLCMD 


32 


(20) 


ADDRESS 


4 


CPPLCMAD 


36 


(24) 


ADDRESS 


4 


CPPLPMAD 


40 


(28) 


ADDRESS 


4 


CPPLCSCB 


44 


(2C) 


ADDRESS 


4 


CPPLCSCR 


48 


(30) 


ADDRESS 


4 


CPPLPSCR 


52 


(34) 


ADDRESS 


4 


CPPLCLCB 


56 


(38) 


FIXED 


4 


CPPLERRW 


60 


(3C) 


ADDRESS 


4 


CPPLCNAM 


64 


(40) 


ADDRESS 


4 


CPPLDABL 


68 


(44) 


ADDRESS 


4 


CPPLMODA 


72 


(48) 


CHARACTER 


2 


CPPLAPPL 


74 


(4A) 


BITSTRING 


1 


CPPLFLG2 




1.. 


. .... 




CPPLMCDF 




.1. 


. .... 




CPPLVOLF 




. .1 


1 1111 




* 


75 


(4B) 


CHARACTER 


1 


« 


76 


(4C) 


ADDRESS 


4 


CPPLCNTN 


80 


(50) 


ADDRESS 


4 


CPPLLMSG 


84 


(54) 


CHARACTER 


4 


* 


88 


(58) 


CHARACTER 




CPPLEND 
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CTAP 



Entry Point: CTABCTAP 

Type 



CTAP 
Offsets 



Length Name 



Description 



COMMAND TABLE - APPLICATION TABLE (CTAP) 






(0) 


CHARACTER 


* 


CTAP 





(0) 


CHARACTER 


8 


CTAPMAIN 





(0) 


CHARACTER 


4 


CTAPVID 


4 


(4) 


FIXED 


2 


CTAPLEN 


6 


(6) 


FIXED 


2 


CTAPCNT 


8 


(8) 


CHARACTER 


28 


CTAPENT(*) 


8 


(8) 


CHARACTER 


8 


CTAPNAME 


16 


(10) 


FIXED 


1 


CTAPTRUN 


17 


(11) 


BITSTRING 


1 


CTAPFLAG 




1.. 







CTAPST 




.1. 


. .... 




CTAPIMED 




..1 


. .... 




CTAPLIST 




... 


1 1111 




CTAPRSVD 


18 


(12) 


CHARACTER 


8 


CTAPRTNM 


26 


(1A) 


CHARACTER 


8 


CTAPTENM 


34 


(22) 


BITSTRING 


2 


* 


Constants 








Length 


Type 


Value 




Name 



VISUAL ID: 'CTAP' 

LENGTH OF CTAP 

# OF COMMAND ENTRIES 

COMMAND NAME 

MIN. # OF CHARACTERS USED IN 

TRUNCATION 

FLAG FIELD 

COMMAND STATUS 

IMMEDIATE COMMAND 

LIST COMMAND 

RESERVED 

COMMAND ROUTINE NAME 

CMD TERMINATION ROUTINE 

FILL UP END OF WORD 

Description 



END OF COMMAND TABLE - APPLICATION TABLE (CTAP) DEFINED 
COMMAND STATUS 



BIT 
BIT 



CMDENABL 
CMDDSABL 



COMMAND STATUS IS ENABLE 
COMMAND STATUS IS DISABL 



CTFU 



Entry Point: Created by invoker of DGTFCTSE 



CTFU 
Offsets 



Type Length Name 
COMMAND TABLE - FUNCTION TABLE (CTFU) 



Description 






(0) 


CHARACTER 


168 


CTFU 





(0) 


CHARACTER 


8 


CTFUMAIN 





(0) 


CHARACTER 


4 


CTFUVID 


4 


(4) 


FIXED 


2 


CTFULEN 


6 


(6) 


FIXED 


2 


CTFUCNT 


8 


(8) 


CHARACTER 


160 


CTFUNMS 


8 


(8) 


CHARACTER 


8 


CTFUNAME 



VISUAL ID: 'CTFU' 

LENGTH OF CTFU 

# OF COMMAND ENTRIES 

COMMAND NAMES 
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CTPL 



Entry Point: Created by invoker of DGTFCTPR 



CTPL 
Offsets 



Type Length Name Description 

COMMAND TABLE PROCESSOR PARAMETER LIST (CTPL) 






(0) 


CHARACTER 


80 


CTPL 





(0) 


CHARACTER 


4 


CTPLVID 


4 


(4) 


FIXED 


2 


CTPLLEN 


6 


(6) 


BITSTRING 


1 


CTPLFLG1 




1.. 







CTPLLOFL 




.1. 







CTPLSCNM 




..1 







CTPLVOLF 






1 




CTPLMCDF 






. 1... 




CTPLSORT 




• . . 


. . 1 . . 




CTPLFILT 




. . . 


. ..11 




CTPLFLGU 


7 


(7) 


CHARACTER 


1 


CTPLPANL 


8 


(8) 


ADDRESS 


4 


CTPLARNM 


12 


(C) 


ADDRESS 


4 


CTPLFONM 


16 


(10) 


CHARACTER 


8 


CTPLCMDN 


24 


(18) 


CHARACTER 


8 


CTPLCMDR 


32 


(20) 


ADDRESS 


4 


CTPLCLAD 


36 


(24) 


FIXED 


2 


CTPLCMDL 


38 


(26) 


FIXED 


2 


CTPLERLN 


40 


(28) 


ADDRESS 


4 


CTPLCSCB 


44 


(2C) 


ADDRESS 


4 


CTPLCSCR 


48 


(30) 


ADDRESS 


4 


CTPLPSCR 


52 


(34) 


ADDRESS 


4 


CTPLCNAM 


56 


(38) 


ADDRESS 


4 


CTPLCNTN 


60 


(3C) 


ADDRESS 


4 


CTPLDABL 


64 


(40) 


ADDRESS 


4 


CTPLMODA 


68 


(44) 


CHARACTER 


2 


CTPLAPPL 


70 


(46) 


CHARACTER 


2 


* 


72 


(48) 


ADDRESS 


4 


CTPLLMSG 


76 


(4C) 


CHARACTER 


4 


* 


80 


(50) 


CHARACTER 




CTPLEND 



VISUAL ID: 'CTPL' 

LENGTH OF CTPL 

FLAG BYTE 1 

LINEOP FLAG 

SOURCE OF THE GENERATED LIST 

1 CATG,0 VTOC 

VOLUME DATA REQUEST FLG 

1 VOLUME DATA REQUESTED 

MODS DATA REQUEST FLG 1 MODS 

DATA REQUESTED 

SORT COMMAND FLAG 

FILTER COMMAND FLAG 

FLAG UNUSED 

PANEL TYPE 

ADDRESS OF ARRAY NAME 

ADDRESS OF FORMAT NAME 

NAME OF COMMAND 

NAME OF COMMAND ROUTINE 

ADDR OF COMMAND LINE 

LEN OF COMMAND LINE 

ERROR LINE NUMBER FIELD 

ADDR OF CURSOR CNTL BLOCK 

CURRENT SCROLL AMNT ADDR 

PREVIOUS SCROLL AMNT ADDR 

ADDRESS OF THE VDEFINED 

CATALOG NAME 

ADDRESS OF THE NAME OF THE 

CATALOG NAME TABLE 

ADDRESS OF DABL 

ADDRESS OF FILTER MODULE NAME 

APPLICATION ID 'DS', 'VO' 

RESERVED 

ADDRESS OF LONG MESSAGE 

RESERVED 

END OF CTPL 
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CTVT 



Entry Point: GDRBCTVT 



CTVT 
Offsets 



Type Length Name Description 

COMMAND TABLE PROCESSOR VECTOR TABLE (CTVT) 







4 

6 

8 

12 

16 

20 

24 

28 

32 

36 



(0) 

(0) 

(4) 

(6) 

(8) 

(C) 

(10) 

(14) 

(18) 

(1C) 

(20) 

(24) 



CHARACTER 

CHARACTER 

FIXED 

FIXED 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

CHARACTER 



36 
4 
2 
2 
4 
4 
4 
4 
4 
4 
4 



CTVT 

CTVTVID 

CTVTLEN 

CTVTUCNT 

CTVTCBE 

CTVTCEN 

CTVTCIN 

CTVTCTE 

CTVTCSE 

CTVTCCK 

CTVTCPR 

CTVTEND 



VISUAL ID: 'CTVT' 
LENGTH OF CTVT 
USE COUNT 

ADDRESS OF PGM DGTFCTB1 
ADDRESS OF PGM DGTFCTE1 
ADDRESS OF PGM DGTFCTIN 
ADDRESS OF PGM DGTFCTTE 
ADDRESS OF PGM DGTFCTSE 
ADDRESS OF PGM DGTFCTCK 
ADDR. OF PGM DGTFCTPR 
END OF CTVT 
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DAB 

Entry Point: DABLDAB 

The DAB must be created by the external application that uses it. Follow the rules in the tables below when 
using a DAB. 

Note: The DABRQST field of the DAB must always be set to X' 80' 



service 
UsiiigDAB 



Field 
Name 



Field 
Value 



DGTFARFl DABVAR 



3 1-bit pointer to a variable containing the column value to use for the search (if 
this DAB's address is contained in the DABL pointed to by SELBDBLI) or a 
31 -bit pointer a variable where retrieved column contents will be stored (if this 
DAB'S address is contained in the DABL pointed to by SELBDBLO). Variables 
must be the same length as the value of DABCLEN. 



DGTFARUl 


DABVAR 3 1 -bit pointer to a variable containing information which is to be written to the 
data set list array in the column specified by DABCNAME. Variables must be 
the same length as the value of DABCLEN. 


DGTFFOEl 


DABVAR 3 1-bit pointer to a variable where retrieved column value will be stored. 
Variables must be the same length as the value of DABCLEN. 




DABCNAME 


Description 


DABTYPE 


DABCLEN 


DABVAR 

Restrictions 


DDISPFLG 


Undisplayed column, represents 
whether entry is displayable 


x'or 


x'ooor 


MustbeX'FO'orX'Fr 


DLINEOP 


Line operator history column 


x'or 


X'OOOA' 




DOBJ 


Data set name 


x'or 


X'002C' 




DALLOCUS 


Allocated used space 


x'lr 


X'0007' 




DDSORG 


Data set organization 


X'07' 


X'0003' 




DRECFMT 


Data set record format 


X'09' 


X'0005' 




DVOLSER 


Volume serial number 


x'or 


X'0006' 




DDEVTYPE 


Generic device type 


X'OE' 


X'0007' 




DENTYP 


Catalog entry type 


x'or 


x'ooor 




DUCAT 


Indicates user catalog or non-user 
catalog 


X'13' 


x'ooor 


Must be 'Y' or 'N' 


DMULTV 


Indicates multi-volume data set 


x'or 


X'0003' 


Must be 'YES' or 'NO ' 
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DAB 
Offsets 



Type Length Name 
DATA ATTRIBUTE BLOCK (DAB) 



Description 






(0) CHARACTER 


24 


DAB 







(0) CHARACTER 


4 


DABVID 


VISUAL ID: 'DAB' 


4 


(4) FIXED 


2 


DABLEN 


LENGTH OF DAB 


6 


(6) FIXED 


1 


DABRS 


RETURN STATUS OF COLUMN NAME 
DAB 


7 


(7) FIXED 


1 


DABFS 


FILTER STATUS OF DSN DAB 


8 


(8) CHARACTER 


8 


DABCNAME 


COLUMN NAME 


16 


(10) CHARACTER 


1 


DABFLAG1 






1 




DABRQST 


REQUEST STATUS FLAG 




.1 




DABDISP 


DISPLAYABLE STATUS FLAG 




..1 




DABEXT 


EXTENSION DAB INDICATOR 




...1 1111 




* 


RESERVED, UNUSED 


17 


(11) BITSTRING 


1 


DABTYPE 


DATA ATTRIBUTES FOR COL 


18 


(12) FIXED 


2 


DABCLEN 


DATA LENGTH OF COLUMN 


20 


(14) ADDRESS 


4 


DABVAR 


ADDRESS OF VARIABLE 


24 


(18) CHARACTER 




DABEND 


END OF DAB 


Constants 








Length 


I Type Value 




Name 


Description 




VALUES FOR DABRS 








1 


DECIMAL 




DABRS 


DATA RETURNED SUCCESSFULLY 


1 


DECIMAL 8 




DABRS 8 


DATA RETURNED AS NULLS 


1 


DECIMAL 1 2 
VALUES FOR DABFS 




DABRS 1 2 


DATA NOT RETURNED 



1 DECIMAL 
1 DECIMAL 
1 DECIMAL 



1 



DECIMAL 




4 
8 

12 



DABFS 
DABFS4 
DABFS8 

DABFS 12 



DATA NOT PROCESSED 

DATA PASSED FILTER CRITERIA 

DATA DID NOT PASS FILTER 

CRITERIA 

DSN NOT FOUND BY CVAFFILT 



DABL 



Entry Point: The DABL must be created by the external application that uses the service that requires the 
DABL. For DGTFARFl, SELBDBLI pomts to the entry pomt for the DABL associated with column 
information used as the search criteria to locate entries in the data set list array. SELBDBLO points to the 
DABL associated with the column information to be retrieved from the entries in the data set list array that 
meet the search criteria. 

DABL 

Offsets Type Length Name Description 

DATA ATTRIBUTE BLOCK LIST (DABL) 



VISUAL ID: 'DABL' 
LENGTH OF DABL 
# OF ENTRIES IN DABL 
LIST OF DAB'S 






(0) 


CHARACTER 


* 


DABL 





(0) 


CHARACTER 


8 


DABLMAIN 





(0) 


CHARACTER 


4 


DABLVID 


4 


(4) 


FIXED 


2 


DABLLEN 


6 


(6) 


FIXED 


2 


DABLNUM 


8 


(8) 


ADDRESS 


4 


DABLDAB(*) 
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ERTB 



Entry Point: GDRBERTB 

ERTB 

Offsets Type 



Length Name 
ISMF ERROR TABLE (ERTB) - 08/15/84 



Description 






(0) 


CHARACTER 


1404 


ERTB 





(0) 


CHARACTER 


84 


ERTBHDR 





(0) 


CHARACTER 


4 


ERTBVID 


4 


(4) 


FIXED 


2 


ERTBLEN 


6 


(6) 


CHARACTER 


2 


* 


8 


(8) 


ADDRESS 


4 


ERTBBUFR 


12 


(C) 


ADDRESS 


4 


ERTBCURR 


16 


(10) 


CHARACTER 


8 


ERTBAPPL 


24 


(18) 


CHARACTER 


8 


ERTBFUNC 


32 


(20) 


CHARACTER 


44 


ERTBOBJ 


76 


(4C) 


CHARACTER 


8 


ERTBPNL 



ERROR TABLE HEADER 

VISUAL ID CONTAINS 'ERTB' 

LENGTH OF ERTB 

RESERVED UNUSED 

PTR TO LOG BUFFER 

PTR TO CURRENT ERTB ENTRY 

ISMF APPLICATION ID 

FUNCTION/DIALOG NAME 

LIST PANEL FUNCTION OBJ 

LAST PANEL DISPLAYED ERTB 

ENTRIES 



84 



(54) CHARACTER 1320 ERTBENT 



ERNT 



Entry Point: Before completing the ERNT, you must set the ERTBCURR field to the value of ERNTPTR 
(found in the current ERNT). The ERTBCURR then contains the entry point value for the ERNT. 

ERTB 

Offsets Type Length Name Description 







ERROR TABLE 


ENTRIES - 08/15/84 







(0 


CHARACTER 


88 


ERNT 







(0 


ADDRESS 


4 


ERNTPTR 


PTR TO NEXT ERTB ENTRY 


4 


(4 


CHARACTER 


84 


ERNTINFO 


ERNT INFORMATION 


4 


(4 


CHARACTER 


8 


ERNTMODN 


MODULE NAME 


12 


(C 


CHARACTER 


8 


ERNTPROC 


PROCEDURE NAME 


20 


(14 


FIXED 


2 


* 


RESERVED UNUSED 


22 


(16 


FIXED 


2 


ERNTRC 


RETURN CODE 


24 


(18 


CHARACTER 


4 


ERNTRSNC 


REASON CODE 


28 


(1C 


CHARACTER 


8 


ERNTSMSG 


SHORT MESSAGE ID 


36 


(24 


CHARACTER 


8 


ERNTLMSG 


LONG MESSAGE ID 


44 


(2C 


CHARACTER 


8 


ERNTSERV 


FAILING EXTERNAL SRVC 


52 


(34 


CHARACTER 


35 


ERNTPD 


PROBLEM DATA 


87 


(57 


CHARACTER 


1 


* 


RESERVED, UNUSED 


Constants 










Length 


Type 


2 Value 




Name 


Description 



END OF ISMF ERROR TABLE (ERTB) 



DECIMAL 
DECIMAL 



15 
1320 



CNTERNT 
LENERNT 



NUMBER OF ERTB ENTRIES 



Appendix E. DFP ISMF Services 343 



ET 



Entry Poim: GDRBET 

ET 

Offsets Type 



Length Name 
ISMF ENVIRONMENT TABLE (ET) 






(0) 


CHARACTER 


52 


ET 





(0) 


CHARACTER 


4 


ETVID 


4 


(4) 


FIXED 


2 


ETLEN 


6 


(6) 


FIXED 


2 


* 


8 


(8) 


FIXED 


4 


ETDSS 



12 



(C) FIXED 



16 (10) CHARACTER 



22 (16) CHARACTER 

30 (IE) CHARACTER 

39 (27) CHARACTER 

45 (2D) CHARACTER 

49 (31) CHARACTER 



4 ETHSM 



ETHSMV 



8 ETFMID 

9 ETCOMPID 
6 ETSYSRES 

4 ETDEVTYP 

3 * 



Description 



VISUAL ID CONTAINS 'ET ' 

LENGTH OF ET 

RESERVED UNUSED 

LEVEL OF DFDSS INSTALLED ON 

SYSTEM 'NNWRRMM'X WHERE NN 

IS 04 IF LEVEL COULD NOT BE 

DETERMINED W IS VERSION RR 

IS RELEASE MM IS MODIFICATION 

LEVEL OF DFHSM INSTALLED ON 

SYSTEM 'NNWRRMM'X WHERE NN 

IS 04 IF LEVEL COULD NOT BE 

DETERMINED W IS VERSION RR 

IS RELEASE MM IS MODIFICATION 

6 CHARACTER VOLUME SERIAL 

NUMBER USED BY DFHSM TO SIGNAL 

MIGRATED NORMALLY 'MIGRAT' 

FMID OF ISMF 

ISMF COMPONENT ID 

VOLSER OF SYSTEM RESIDENCE 

VOLUME 

DEVICE TYPE OF SYSRES 

RESERVED, UNUSED 



FOVT 



Entry Point: GDRBFOVT 

FOVT 

Offsets Type 



Length Name 
FORMAT SERVICE VECTOR TABLE (FOVT) 






(0) 


CHARACTER 


84 


FOVT 





(0) 


CHARACTER 


4 


FOVTVID 


4 


(4) 


FIXED 


2 


FOVTLEN 


6 


(6) 


FIXED 


2 


FOVTUCNT 


8 


(8) 


ADDRESS 


4 


FOVTBEG 


12 


(C) 


ADDRESS 


4 


FOVTDONE 


16 


(10) 


ADDRESS 


4 


FOVTFIND 


20 


(14) 


ADDRESS 


4 


FOVTGTLA 


24 


(18) 


ADDRESS 


4 


FOVTGTVL 


28 


(1C) 


ADDRESS 


4 


FOVTHIDE 


32 


(20) 


ADDRESS 


4 


FOVTHILT 


36 


(24) 


ADDRESS 


4 


FOVTHRD 


40 


(28) 


ADDRESS 


4 


FOVTINIT 


44 


(2C) 


ADDRESS 


4 


FOVTLAI 


48 


(30) 


ADDRESS 


4 


FOVTLOAD 


52 


(34) 


ADDRESS 


4 


FOVTMOVE 


56 


(38) 


ADDRESS 


4 


FOVTPCSR 



Description 



VISUAL ID: 'FOVT' 
LENGTH OF FOVT 
USE COUNT 

ADDRESS OF FOBEGIN MODULE 
ADDRESS OF FODONE MODULE 
ADDRESS OF FOFIND MODULE 
ADDRESS OF FOGETLA MODULE 
ADDR. OF FOGETVLA MODULE 
ADDRESS OF FOHIDE MODULE 
ADDRESS OF FOHILT MODULE 
ADDRESS OF FOHRD MODULE 
ADDRESS OF FOINIT MODULE 
ADDRESS OF FOLAI MODULE 
ADDRESS OF FOLOAD MODULE 
ADDRESS OF FOMOVE MODULE 
ADDRESS OF FOPCSR MODULE 
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60 


(3C) 


ADDRESS 


4 


FOVTPTLA 


64 


(40) 


ADDRESS 


4 


FOVTPTVL 


68 


(44) 


ADDRESS 


4 


FOVTQCSR 


72 


(48) 


ADDRESS 


4 


FOVTQURY 


76 


(4C) 


ADDRESS 


4 


FOVTTERM 


80 


(50) 


ADDRESS 


4 


FOVTAREA 


84 


(54) 


CHARACTER 




FOVTEND 



ADDRESS OF FOPUTLA MODULE 
ADDR. OF FOPUTVLA MODULE 
ADDRESS OF FOQCSR MODULE 
ADDRESS OF FOQUERY MODULE 
ADDRESS OF FOTERM MODULE 
ADDR OF FOFXAREA MODULE 
END OF FOVT 



GDRB 



Entry Point: Address is in RIO at all times. 

GDRB 

Offsets Type Length Name 



Description 
ISMF GLOBAL DATA REPOSITORY BLOCK (GDRB) 






(0 


CHARACTER 


96 


GDRB 





(0 


CHARACTER 


4 


GDRBVID 


4 


(4 


FIXED 


2 


GDRBLEN 


6 


(6 


FIXED 


2 


* 


8 


(8 


ADDRESS 


4 


GDRBARVT 


12 


(C 


ADDRESS 


4 


GDRBASAB 


16 


(10 


ADDRESS 


4 


GDRBCTAB 


20 


(14 


ADDRESS 


4 


GDRBDAAB 


24 


(18 


1 ADDRESS 


4 


GDRBDSAB 


28 


(1C 


1 ADDRESS 


4 


GDRBERTB 


32 


(20 


1 ADDRESS 


4 


GDRBET 


36 


(24 


1 ADDRESS 


4 


GDRBFOVT 


40 


(28 


ADDRESS 


4 


GDRBFSAB 


44 


(2C 


ADDRESS 


4 


GDRBFST 


48 


(30 


ADDRESS 


4 


GDRBIMTT 


52 


(34 


ADDRESS 


4 


GDRBLLBL 


56 


(38 


ADDRESS 


4 


GDRBLPAB 


60 


(3C 


ADDRESS 


4 


GDRBMDAB 


64 


(40 


ADDRESS 


4 


GDRBPVT 


68 


(44 


ADDRESS 


4 


GDRBSCT 


72 


(48 


ADDRESS 


4 


GDRBSRVT 


76 


(4C 


ADDRESS 


4 


GDRBTPTT 


80 


(50 


ADDRESS 


4 


GDRBISPF 


84 


(54 


ADDRESS 


4 


GDRBCTVT 


88 


(58 


ADDRESS 


4 


GDRBDCMD 


92 


(5C 


T^DRESS 


4 


GDRBDEVT 



VISUAL ID CONTAINS 'GDRB' 
LENGTH OF GDRB 
RESERVED 

ARRAY SERVICES VECTOR TABLE 
ARRAY SERVICES ANCHOR BLOCK 
COMMAND TABLE ANCHOR BLOCK 
DATA ACQUISITION ANCHOR BLK 
DATA SET ANCHOR BLOCK 
ERROR TABLE ADDRESS 
ENVIRONMENT TABLE 
FORMAT SERVICE VECTOR TABLE 
FORMAT SERVICE ANCHOR BLOCK 
FROZEN STORAGE TABLE PTR 
INTER MODULE TRACE TABLE 
LOAD LIST BLOCK POINTER 
LINE OPERATOR ANCHOR BLOCK 
MAIN DIALOG ANCHOR BLOCK 
PROFILE VARIABLE TABLE 
STORAGE CONTROL TABLE PTR 
SERVICE ROUTINE VECTOR TBL 
TRACE POINT TRACE TABLE PTR 
POINTER TO ISPF 
POINTER TO CTVT 
PTR TO ZTRAIL TRUNC REMAIN 
PTR TO DEVICE TYPE TABLE 



EvriT 

Entry Point: Before completing the IMTT, you must set the IMTTCURR field to the value of IMNTPTR 
(found in the current ERNT). The IMTTCURR then contains the entry point value for the IMTT. 

IMTT 

Offsets Type Length Name Description 

ISMF INTER MODULE TRACE TABLE (IMTT) 



INTER MODULE TRACE TABLE HDR 

VISUAL ID CONTAINS 'IMTT' 

LENGTH OF IMTT 

RESERVED UNUSED 

POINTER TO THE CURRENT ENTRY 

RESERVED UNUSED IMTT ENTRIES 






(0) 


CHARACTER 


6288 


IMTT 





(0) 


CHARACTER 


16 


IMTTHDR 





(0) 


CHARACTER 


4 


IMTTVID 


4 


(4) 


FIXED 


2 


IMTTLEN 


6 


(6) 


FIXED 


2 


* 


8 


(8) 


ADDRESS 


4 


IMTTCUR 


12 


(C) 


CHARACTER 


4 


* 


16 


(10) 


CHARACTER 


6272 


IMNTENT 
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IMNT 



Entry Point: IMTTCURR 

IMTT 

Offsets Type 



Length Name 
IMTT ENTRIES 



Description 






(0) 


CHARACTER 


56 


IMNT 







(0) 


ADDRESS 


4 


IMNTPTR 


PTR TO NEXT IMTT ENTRY 


4 


(4) 


CHARACTER 


52 


IMNTINFO 


IMNT INFORMATION 


4 


(4) 


CHARACTER 


8 


IMNTEMID 


MODULE ID 


12 


(C) 


ADDRESS 


4 


IMNTREG1 


FARM LIST REG REG 1 


16 


(10) 


ADDRESS 


4 


IMNTREGB 


CURRENT WORK AREA ADDR 


20 


(14) 


CHARACTER 


35 


IMNTUSER 


USER AREA 


55 


(37) 


CHARACTER 


1 


* 


RESERVED, UNUSED 


Constants 










Length 


Type 


Value 




Name 


Description 




END ( 


DF ISMF INTER- 


-MODULE TRACE 


TABLE (IMTT) 



DECIMAL 
DECIMAL 



112 
6272 



CNTIMNT 
LENIMNT 



NUMBER OF IMNT ENTRIES 



LOGB 



Entry Point; ERTBBUFR 

LOGB 

Offsets Type 



Length Name 
I SMF LOG BUFFER ( LOGB ) 



Description 






(0) 


CHARACTER 


236 


LOGB 





(0) 


CHARACTER 


4 


LOGBVID 


4 


(4) 


FIXED 


2 


LOGBLEN 


6 


(6) 


CHARACTER 


2 


* 


8 


(8) 


CHARACTER 


72 


PGMLOG08 


8 


(8] 


CHARACTER 


8 


LOGBAPPL 


16 


(10] 


CHARACTER 


8 


LOGBMODN 


24 


(18] 


CHARACTER 


8 


LOGBPROC 


32 


(20] 


CHARACTER 


8 


LOGBPNL 


40 


(28] 


CHARACTER 


8 


LOGBSERV 


48 


(30] 


CHARACTER 


8 


LOGBJBNM 


56 


(38] 


CHARACTER 


8 


LOGBJBNO 


64 


(40] 


CHARACTER 


8 


LOGBSMSG 


72 


(48; 


CHARACTER 


8 


LOGBLMSG 


80 


(50 


CHARACTER 


11 


PGML0G1 1 


80 


(50 


CHARACTER 


11 


LOGBFUNC 


91 


(5B 


CHARACTER 


1 


* 


92 


(5C 


CHARACTER 


44 


PGML0G44 


92 


(5C 


CHARACTER 


44 


LOGBOBJ 


136 


(88 


CHARACTER 


54 


PGMLOG54 


136 


(88 


1 CHARACTER 


54 


LOGBJBDS 


190 


(BE 


CHARACTER 


2 


« 


192 


(CO 


1 CHARACTER 


8 


PGMLOG04 


192 


(CO 


1 CHARACTER 


4 


LOGBRC 


196 


(C4 


) CHARACTER 


4 


LOGBRSNC 


200 


(C8 


) CHARACTER 


35 


PGMLOG35 


200 


(C8 


) CHARACTER 


35 


LOGBPD 


235 


(EB 


) CHARACTER 


1 


« 



VISUAL ID CONTAINS 'LOGB' 

LENGTH OF LOGB 

RESERVED 

VARS WITH LENGTH OF 8 

ISMF APPLICATION ID 

MODULE ID 

PROCEDURE ID 

LAST PANEL DISPLAYED 

NAME OF FAILING SERVICE 

SUBMIT JOB NAME 

SUBMIT JOB NUMBER 

SHORT MESSAGE 

LONG MESSAGE 

VARS WITH LENGTH OF 44 

FUNCTION/DIALOG NAME 

RESERVED UNUSED 

VARS WITH LENGTH OF 44 

LIST PANEL FUNCTION OBJ 

VARS WITH LENGTH OF 54 

SUBMIT DATA SET NAME 

RESERVED UNUSED 

VARS WITH LENGTH OF 4 

RETURN CODE 

REASON CODE 

VARS WITH LENGTH OF 35 

PROBLEM DATA 

FILL UP REST OF WORD 
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LPAP 



Entry Point: LPABLPAP 

LPAP 

Offsets Type 



Length Name Description 

LINE OPERATOR TABLE - APPLICATION TABLE (LPAP) 






(0) 


CHARACTER 


« 


LPAP 





(0) 


CHARACTER 


8 


LPAPMAIN 





(0) 


CHARACTER 


4 


LPAPVID 


4 


(4) 


FIXED 


2 


LPAPLEN 


6 


(6) 


FIXED 


2 


LPAPCNT 


8 


(8) 


CHARACTER 


28 


LPAPENT ( * 


8 


(8) 


CHARACTER 


8 


LPAPLONM 


16 


(10) 


FIXED 


1 


LPAPTRUN 


17 


(11) 


CHARACTER 


3 


* 


20 


(14) 


CHARACTER 


8 


LPAPRTNM 


28 


(1C) 


CHARACTER 


8 


LPAPTENM 



VISUAL ID: 'LPAP' 

LENGTH OF LPAP 

# OF LINE OPERATORS 

LINE OPERATOR NAME 

MIN. # OF CHARACTERS USED 

TRUNCATION 

RESERVED, UNUSED 

LINE OP ROUTINE NAME 

TERMINATION ROUTINE 



IN 



LPCB 

Entry Point: LPPLLPCB (line operator is iiivoker)/CPPLCSCB (command is invoker) 

LPCB 

Offsets Type Length Name Description 





LIST PANEL CURSOR 


CONTROL BLOCK (LPCB) 


=2::==:=:^:==:=:^=:=^==:==:=:^^^^^=:^:=:==:^:== 





(0) 


CHARACTER 


30 


LPCB 







(0) 


CHARACTER 


4 


LPCBVID 


VISUAL ID: 'LPCB' 


4 


(4) 


FIXED 


2 


LPCBLEN 


LENGTH OF LPCB 


6 


(6) 


FIXED 


2 


LPCBENO 


ENTRY NUMBER 


8 


(8) 


CHARACTER 


1 


LPCBMFG 


MULTI LINE ENTRY FLAG 


9 


(9) 


CHARACTER 


1 


* 


RESERVED, UNUSED 


10 


(A) 


FIXED 


2 


LPCBMLN 


MULTI LNE ENTRY INDICATOR 


12 


(C) 


CHARACTER 


2 


LPCBCTG 


COLUMN TAG 


14 


(E) 


CHARACTER 


2 


* 


RESERVED, UNUSED 


16 


(10) 


CHARACTER 


8 


LPCBAREA 


AREA NAME 


24 


(18) 


FIXED 


4 


LPCBRND 


ROW ID NAME 


28 


(1C) 


FIXED 


2 


LPCBOFF 


OFFSET WITHIN AREA 


30 


(IE) 


CHARACTER 




LPCBEND 


END OF LPCB 
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LPPL 



Entry Point: Rl on entry to line operator routine 

LPPL 

Offsets Type Length Name 



Description 



LINE OPERATOR PROCESSOR PARAMETER LIST (LPPL) PASSES TO THE 
LINE OPERATOR ROUTINES 






(0) 


CHARACTER 


68 


LPPL 





(0) 


CHARACTER 


4 


LPPLVID 


4 


(4) 


FIXED 


2 


LPPLLEN 


6 


(6) 


BITSTRING 


1 


LPPLFLG1 




1 . . 


. .... 




LPPLSTD 




.1. 


, 


... 




LPPLTEOA 




..1 


, 


... 




LPPLTEOL 




. . • 


1 


... 




LPPLLOFL 




. . . 


. 


1... 




LPPLLAST 




. . . 


, 


.1.. 




LPPLSMSG 




. . . 


. 


.1. 




LPPLSCNM 




• • • 


, 


...1 




LPPLHIDE 


7 


(7) 


BITSTRING 


1 


LPPLFLG2 


8 


(8) 


ADDRESS 


4 


LPPLARAD 


12 


(C) 


ADDRESS 


4 


LPPLFOAD 


16 


(10) 


ADDRESS 


4 


LPPLCLCB 


20 


(14) 


CHARACTER 


8 


LPPLLO 


28 


(1C) 


FIXED 


4 


LPPLROWI 


32 


(20) 


FIXED 


2 


LPPLENT 


34 


(22) 


CHARACTER 


1 


LPPLCMDF 


35 


(23) 


CHARACTER 


1 


* 


36 


(24) 


ADDRESS 


4 


LPPLCNAM 


40 


(28) 


ADDRESS 


4 


LPPLLAIA 


44 


(2C) 


ADDRESS 


4 


LPPLROWA 


48 


(30) 


FIXED 


4 


LPPLLAIT 


52 


(34) 


ADDRESS 


4 


LPPLLPCB 


56 


(38) 


ADDRESS 


4 


LPPLCNTN 


60 


(3C) 


ADDRESS 


4 


LPPLLMSG 


64 


(40) 


CHARACTER 


4 


* 


68 


(44) 


CHi 


\RACTER 




LPPLEND 



VISUAL ID: 'LPPL' 

LENGTH OF LPPL 

FLAG FIELD 

STD INVOCATION 

INVOKE AT END OF APPL 

INVOKE AT END OF LIST? 

ACTIVE LINE OPERATOR? 

LAST USED MODE? 

MSG ID SET IN ERTB ? 

LIST GEN'D FR CATALOG 

HIDE LINE OP 

FLAG FIELD , UNUSED 

ARRAY NAME ADDRESS 

FORMAT NAME ADDRESS 

COMMAND/LINE OP CNTL BLK 

LINE OPERATOR IN PROGRESS 

ROWID # OF THE LAI ENTRY 

LAI ENTRY # 

COMMAND FLAG 

RESERVED 

ADDRESS OF CATALOG NAME FOR 

DATA SET APPLICATION 

ADDRESS OF LAI 

ADDRESS OF ROW IDS 

TOTAL ENTRIES IN LAI 

LIST PNL CURSOR CTL BLK 

ADDR OF THE NAME OF THE 

CATALOG NAME TABLE FOR DATA 

SET APPLICATION 

ADDR OF THE LONG MSG 

RESERVED UNUSED 

END OF LPPL 
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PCCB 

Entry Point: CPPLCSCB 

PCCB 

Offsets Type 



PVT 



Length Name 
PANEL CURSOR CONTROL BLOCK (PCCB) 



Description 






(0) 


CHARACTER 


16 


PCCB 







(0) 


CHARACTER 


4 


PCCBVID 


VISUAL ID: 'PCCB' 


4 


(4) 


FIXED 


2 


PCCBLEN 


LENGTH OF PCCB 


6 


(6) 


FIXED 


2 


* 


RESERVED, UNUSED 


8 


(8) 


ADDRESS 


4 


PCCBCFAD 


CURSOR FIELD ADDRESS 


12 


(C) 


ADDRESS 


4 


PCCBCOAD 


CURSOR OFFSET ADDRESS 


16 


(10) 


CHARACTER 




PCCBEND 


END OF PCCB 



Entry Point: GDRBPVT 

PVT 

Offsets Type 



Length Name 
ISMF PROFILE VARIABLE TABLE (PVT) 



Description 






(0) 


CHARACTER 


16 


PVT 





(0) 


CHARACTER 


4 


PVTVID 


4 


(4) 


FIXED 


2 


PVTLEN 


6 


(6) 


FIXED 


2 


* 


8 


(8) 


ADDRESS 


4 


PVTL72 


12 


(C) 


ADDRESS 


4 


PVTL1 



VISUAL ID CONTAINS 'PVT 

LENGTH OF PVT 

RESERVED 

PTR TO VARS WITH LEN 72 

PTR TO VARS WITH LEN 1 
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PVTV 



Eniry Point: PVTL72 (field PVTL72 in control block PVT— for straeture PGMPVT72) 
PVTLl (field PVTLl in control block PVT— for structure PGMPVTOl) 

PVTV 



Offsets 


Type 


Length 


Name 




Description 


ISMF 


PROFILE 


VARIABLE ' 


lABLE 


VARIABLES 


(PVTV) 






72 

144 

216 

288 

360 

432 

504 
576 
648 
720 
792 
864 
936 
1008 

1080 

1152 

1224 

1296 

1368 

1440 

PVTV 
Offsets 





1 

2 

3 



(0 
(0 

(48 

(90 

(D8 

(120 

(168 

(1B0 

(1F8 
(240 
(288 
(2D0 
(318 
(360 
(3A8 
(3F0 

(438 

(480 

(4C8 

(510 

(558 

(5A0 



(0 
(0 
(1 
(2 
(3 



CHARACTER 
CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 
CHARACTER 
CHARACTER 
CHARACTER 
CHARACTER 
CHARACTER 
CHARACTER 
CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 

CHARACTER 

Type 
CHARACTER 
CHARACTER 
CHARACTER 
CHARACTER 
CHARACTER 



1512 
72 

72 

72 

72 

72 

72 

72 

72 
72 
72 
72 
72 
72 
72 
72 

72 

72 

72 

72 

72 

72 



PGMPVT72 
APPFDE11 

APPFDE12 

APPFDE13 

APPFDE14 

APPFDE15 

APPFDE16 

APPFDE17 

APPFJ0B1 
APPFJ0B2 
APPFJ0B3 
APPFJ0B4 
APPFJ0B5 
APPFJ0B6 
APPFJ0B7 
APPFDE2 1 

APPFDE22 

APPFDE23 

APPFDE24 

APPFDE25 

APPFDE26 

APPFDE27 



PVT VARS WITH 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
JOB STATEMENT 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 
DFDSS EXECUTE 
VARIABLE 



LEN OF 72 
STATEMENT 

STATEMENT 

STATEMENT 

STATEMENT 

STATEMENT 

STATEMENT 

STATEMENT 

VARIABLE 
VARIABLE 
VARIABLE 
VARIABLE 
VARIABLE 
VARIABLE 
VARIABLE 
STATEMENT 

STATEMENT 

STATEMENT 

STATEMENT 

STATEMENT 

STATEMENT 

STATEMENT 



Length Name 



4 PGMPVTOl 

1 APPFLDED 

1 APPFLIMT 

1 APPFLTPT 

1 APPFLRFA 



Description 

PVT VARS WITH LEN OF 01 
LOGGING/ABEND CONTROL VARIABLE 
LOGGING/ABEND CONTROL VARIABLE 
LOGGING/ABEND CONTROL VARIABLE 
LOGGING/ABEND CONTROL VARIABLE 
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SELB 

Entry Point: This control block and all control blocks addressed by it must be created by the external 
application that uses the service requiring the control block. 

When using the SELB, observe the requirements in the following table. 

Service Field Name Field Vahie 

Using SELB 

DGTFARFl SELBARNM Value pointed to by CPPLARNM 

SELBNP 'N' 

SELBNO 15-bit value set to X' 1 • 



SELB 
Offsets 



Type Length Name 
SELECT BLOCK (SELB) 



Description 







4 

6 

8 

16 

17 

18 

20 



21 
24 
28 
32 
36 
40 



(0) 

(0) 

(4) 

(6) 

(8) 

(10) 

(11) 

(12) 

(14) 

1. . 

.1. 

. .1 

(15) 

(18) 

(1C) 

(20) 

(24) 

(28) 



CHARACTER 

CHARACTER 

FIXED 

FIXED 

CHARACTER 

CHARACTER 

CHARACTER 

FIXED 

BITSTRING 



CHARACTER 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

CHARACTER 



40 
4 
2 
2 
8 
1 
1 
2 
1 



SELB 

SELBVID 

SELBLEN 

SELBARNM 
SELBNP 

* 

SELBLNO 

SELBFLG1 

SELBKEEP 

SELBUSE 

SELBONE 

* 

SELBDBLO 

SELBCNDL 

SELBDBLI 

SELBRID 

SELBEND 



VISUAL ID: 'SELB' 

LENGTH OF SELB 

RESERVED, UNUSED 

ARRAY NAME 

DIRECTION OF SEARCH 

RESERVED, UNUSED 

NTH LINE TO BE RETRIEVED 

FLAG FIELD 

SAVE SEARCH CRITERIA 

USE OLD SEARCH CRITERIA 

USE NEW SEARCH CRITERIA 

RESERVED, UNUSED 

ADDR OF DABL FOR OUTPUT 

ADDRESS OF CONDITION LIST 

ADDR OF DABL FOR INPUT 

ADDR OF VAR TO PUT ROWID 

END OF SELB 
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SRVT 

Entry Point: GDRBSRVT 

SRVT 

Offsets Type 







4 

6 



8 
12 
16 
20 
24 
28 
32 
36 

40 

44 

48 
52 
56 
60 
64 
68 
72 
76 
80 
84 
88 
92 
96 
100 
104 
108 



(0 
(0 
(0 
(4 
(6 
(8 
(C 
(10 
(14 
(18 
(1C 
(20 
(24 

(28 

(2C 

(30 
(34 
(38 
(3C 
(40 
(44 
(48 
(4C 
(50 
(54 
(58 
(5C 
(60 
(64 
(68 
(6C 



Constants 
Length Type 



CHARACTER 

CHARACTER 

CHARACTER 

FIXED 

FIXED 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

7UDDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 

ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 
ADDRESS 

Value 



Length 
112 
8 
4 
2 
2 
4 
4 
4 
4 
4 
4 
4 
4 



Name 
SRVT 
SRVTHDR 
SRVTVID 
SRVTLEN 
* 

SRVTPRO 1 
SRVTPR02 
SRVTEPOl 
SRVTGM01 
SRVTFM01 
SRVTLDO 1 
SRVTDT01 
SRVTDV01 



4 SRVTW01 



SRVTWOO 1 

SRVTARB1 
SRVTARN1 
SRVTF0B1 
SRVTF0N1 
SRVTAS01 
SRVTCDO 1 
SRVTDAOO 
SRVTLGO 1 
SRVTCC01 
SRVTCTB1 
SRVTCTE1 
SRVTCDO 2 
SRVTCDO 3 
SRVTCD04 
SRVTCDO 5 
SRVTCDQ1 

Name 



Description 

SRVT HEADER 

SRVT VISUAL ID IS 'SRVT' 

LENGTH OF SRVT 

UNUSED, RESERVED 

PROLOG ENTRY POINT ADDRESS 

PROLOG ENTRY POINT ADDRESS 

EPILOG ENTRY POINT ADDRESS 

GETMEM ENTRY POINT ADDRESS 

FREEMEM ENTRY POINT ADDRESS 

LOAD ENTRY POINT ADDRESS 

DELETE ENTRY POINT ADDRESS 

DSN VERIFICATION ENTRY POINT 

ADR 

VOL VERIFICATION ENTRY POINT 

ADR 

WORD PARSER ENTRY POINT 

ADDRESS 

ARRAY SERVICE INITIALIZATION 

ARRAY SERVICE TERMINATION 

FORMAT SERVICE INITIALIZATION 

FORMAT SERVICE TERMINATION 

RACROUTE SERVICE ROUTINE 

CONVERSION SERVICE ROUTINE 

DATA ACQUISITION EPA 

LOG SERVICE ROUTINE EPA 

SELECT FILTER VERIFICATION 

COMMAND TABLE BEGIN 

COMMAND TABLE END 

CONVERSION SERVICE ROUTINE 

CONVERSION SERVICE ROUTINE 

CONVERSION SERVICE ROUTINE 

CONVERSION SERVICE ROUTINE 

CONVERSION TABLE QUERY ROUTINE 

Description 



ISMF COMMON SERVICE ROUTINE VECTOR TABLE (SRVT) 



DECIMAL 



18 



SRVTCNT 
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Index 



s 



ABE appendage 71 
abnormal-end appendage 

See ABE appendage 
access method routines, functions performed in I/O 

operations 63 
accessing VTOCs and VTOC indexes 42-60 
alias name 

of UCS images for JES2 225 
allocating DASD space 5 
allocation retrieval area 

format 144 
allocation retrieval list 

format 144 
altering DADSM processing 125 
alternate track 

assigning with ATLAS 83 
AM operand 

in DEBCHK macro 153 
APF (authorized program facility) requirements 18 
appendages 

ABE (abnormal end) 71 

CHE (channel end) 71 

entry points 71 

EOE (end of extent) 71 

listing in SYS 1 .PARMLIB 7 1 

naming convention 71 

PCI (program controlled interruption) 71 

PGFX (page fix) 94 

programming restrictions 71 

returns 71 

SIO (start I/O) 71 
ARVT (array service vector table) 335 
assigning alternate track with ATLAS 83-85 
ATLAS macro 

coding example 85 

how to use 85 

lOBSENS fields with 85 

operations performed 86 

return codes 86 

specification 83-85 

unit check with 85 

with track overflow option 84 
authorized appendage list 71 
authorized program facility 

See APF 



BALANCE operand (TRKCALC macro) 164, 166 
BFALN operand (DCB macro) 77 
BFTEK operand (DCB macro) 77 
bit maps 

of allocated DSCBs 14 
of allocated VIRs 14 
block ID 

setting in JFCB for high-speed positioning 149 
BSAM (basic sequential access method) 

defaulting buffer number 125 
BUFCB operand (DCB macro) 77 
buffer 

DASD data sets 

performance considerations with 

BUFNO 229 
selecting quantity with BUFNO 229 
lists 49 

entry format 46 
format 45-47 
function 45 
header format 45 
how created 45 
releasing 49 
releasing 49 
BUFL operand (DCB macro) 77 
BUFNO operand (DCB macro) 77 
defaulting in OPEN installation exit 

example (QSAM) 305 
selecting value for DASD data sets 229 
performance considerations 229 







CAMLST macro 

with RENAME operand 38-41 

with SCRATCH operand 33-37 

with SEARCH operand 29-3 1 

with SEEK operand 31-33 
catalogs 

dummy module 227 
CCW (channel command word) 

See also channel programs 
CENDA operand (DCB macro) 
channel-end appendage 

See CHE appendage 
channel programs 

appendages used with 71 

execution 68-69 

initiation 68-69 

related 71 

restrictions on modification 70 



69 



75 
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translation, virtual addresses to real 
addresses 95-97 
CHE appendage 71 
checking the DEB (DEBCHK) 151-155 
checkpoint data set 

processed with EXCP macro 79 
CLCB (command/line operator control block) 335 
CLOSE macro 

used with EXCP macro 83 
used with XDAP macro 104 
codes 

returned with error message 298-303 
routing and descriptor 298 
command retry 72 
communication vector table (CVT) mapping macro 

See CVT mapping macro 
completion codes 

See also return codes 
following use of EXCP macro 93 
following use of XDAP macro 105 
CONH (conditional control block header) 336 
control blocks 
PIRL 161 
used with EXCP 
DCB 73-80 
DEB 92 
ECB 92 
lOB 88-91 
control password 116 
conversion 

of sector value for RPS devices 108 
routine, actual track address to relative track 
address 107 

register usage 107 
routine, relative track address to actual track 
address 106 

register usage 106 
return codes 107 
copy operation 
DASD volume 

indexed VTOC requirements 18 
nonindexed VTOC requirements 18 
copying 

DASD volumes 18 
CPPL (command processor parameter list) 337 
creating 

protected data sets 113 
CTAP (command table - application table) 338 
CTFU (command table - function table) 338 
CTPL (command table processor parameter list) 339 
CTVT (command table processor vector table) 340 
CVAF (common VTOC access facility) 
filter service 

control blocks required for 53 
reading sets of DSCBs with 52 
processing of GTF trace 6 1 
serialization 42 
volume identiHcation to 42 
VTOC access macros 

CVAFDIR examples 259-270 



C VAFFILT example 27 1 -277 
CVAFSEQ example 277-292 
CVAFTST and CVAFDSM 

examples 292-296 
uses and syntax 231-258 
CVAF parameter list 

See CVPL 
CVAFDIR macro 

examples 259-270 
how to use 47 
parameters 232, 237 
return codes 238 
syntax 231 
uses 231 
CVAFDSM macro 
example 292-296 
how to use 59 
parameters 239-244 
return codes 244 
syntax 239 
uses 239 
CVAFFILT macro 

control block address resolution 245-246 
examples 271-277 
filter criteria list 
entry format 56 
header format 54 
how to use 52 
invocation sequences 

example 57 
parameters 246-249 
partially qualified names 

examples 250 
RESUME capability 52 
return codes 249 
syntax 245 
uses 245 
CVAFSEQ macro 

examples 277-292 
how to use 50 
parameters 251-255 
return codes 256 
sjmtax 251 
uses 251 
CVAFTST macro 
example 292-296 
return codes 258 
syntax 257 
uses 257 
CVFCTN field of CVPL 
contents 45 
definitions 45 
CVPL (CVAF parameter list) 
format 44 
fimction 43-44 
when created 43 
CVSTAT codes 298 

CVT (communication vector table) mapping 
macro 129 
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D 



DAB (data attrabute block) 341 
DABL (data attribute block list) 342 
DADSM 

allocate routine 5 

return codes 181 
overview 1 
postprocessing exit 

when given control 125 
pre/postprocessing exits 125 

data passed from DADSM 125 
format- 1 DSCB passed by IGGPREOO 125 
operating environment 125 
parameter list (lEPL) 125 
register contents 125 
rejecting a DADSM request 125 
return codes from IGGPREOO 125 
system control block addresses 125 
preprocessing exit 

altering DADSM processing 125 
when given control 125 
DASD (direct access storage devices) 
obtaining free space 

LSPACE macro 20-29 
reading and writing to 

XDAP macro 99-103 
DASD calculation (DCS) exits 

See DCS pre/postcalculation exits 
data control block 

See DCB (data control block) 
data extent block (DEB) 

See DEB 
data management 

ABEND installation exit 125 
modifying 125 
parameter list (OADCL) 125 
register contents 125 
return codes 125 
data set 
security 

See password protection 
data set control block (DSCB) 

See DSCB 
DCB macro 

used with EXCP macro 68, 73-80 
used mth XDAP macro 100 
DCB OPEN installation exit 125 
description 125 
example 305 

example, defaulting buffer number (QSAM) 305 
example, requesting partial release 305 
example, updating secondary space data 305 
operating environment 125 
parameter list (OIEXL) 125 
register contents 125 
return codes 125 
when executed 125 
DCBDIRCT field of DCB 76 



DCBFDAD field, maintaining 76 
DCBIFLGS field of DCB, permanent I/O error 

mdicators 70 
DCBOFLGS field of DCB, meanings of bit 

settings 81-82, 83 
DCBTRBAL field, maintaining 78 
DCS (DASD calculation services) 
exit routines 125 
overview 125 

parameter list (DCSIEPL) 125 
register contents 125 
postcalculation exit 
overview 125 
return codes 125 
precalculation exit 
overview 125 
return codes 125 
DCSIEPL (DCS pre/postcalculation exit parameter 

Ust) 125 
DD operand (TRKCALC macro) 165, 167 
DDNAME operand (DCB macro) 74 
DDR (djmamic device reconfiguration), repositioning 

tape data sets 74 
DEB (data extent block) 
fields 92 
obtaining 42 
used with EXCP macro 68 
vaUdating with DEBCHK 151-155 
DEBCHK macro 

functions of 151-155 
register contents 154 
return codes 155 
specification 152-155 
defaulting buffer number 
for BSAM 125 
for QSAM 125 
in OPEN installation exit 
example for QSAM 305 
defective track 

See assigning alternate track with ATLAS 
define extent CCW 

in EXCP processing 69 
deleting 

a data set 

coding example 35 
macro instructions for 33 
when volume not mounted 34 
DEMOUNT parameter (MSGDISP macro) J 9 1 
DEN operand (DCB macro) 79 
DEQ macro 

at demount facility 147 
DEVD operand (DCB macro) 77-79 
device characteristics 1 29- 1 3 5 
device dependent parameters in DCB 77-80 
DEVT AB operand (TRKCALC macro) 1 64, 1 66 
DEVTYPE macro 
EXECUTE form 

specification 136 
for RPS devices 130 
list form 

specification 136 
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output from 130-135 
return codes 133 
specification 1 30- 131 
DFP ISMF common services 330 

control blocks available to external applications 
ARVT (array service vector table) 335 
CLCB (command/line operator control 

block) 335 
CONH 336 
CONH (conditional control block 

header) 336 
CPPL (command processor parameter 

Ust) 337 
CTAP (command table - application 

table) 338 
CTFU (command table - function table) 338 
CTPL (conmiand table processor parameter 

list) 339 
CTVT (command table processor vector 

table) 340 
DAB (data attribute block) 341 
DABL (data attribute block list) 342 
ERNT (error table entries) 343 
ERTB (ISMF error table) 343 
ET (ISMF environment table) 344 
FOVT (format service vector table) 344 
GDRB (ISMF global data repository 

block) 345 
IMNT (IMTT entries) 346 
IMTT (ISMF inter module trace table) 345 
introduction 335 
LOGB (ISMF log buffer) 346 
LPAP (line operator table - application 

table) 347 
LPCB (list panel cursor control block) 347 
LPPL (line operator processor parameter 

list) 348 
PCCB (panel cursor control block) 349 
PVT (ISMF profUe variable table) 349 
PVTV (ISMF profile variable table 

variables) 350 
SELB (select block) 351 
SRVT (ISMF common service routine vector 

table) 352 
functions 

IGBDISOO 330 
messages available to external applications 331 
DFP ISMF services 
control blocks 

locating 308 
error logging 309 
functions 

data set name syntax verification 311 

decrement use count 3 10 

enable valid commands 327 

find an entry in the data set list array 321 

free memory 314 

free storage and exit 313 

get storage 315 

load a module 316 

obtain automatic data area 318 



obtain count of data sets 323 

obtain input information from the screen area 
image 328 

place information in the ISPF log 317 

position current row pointer at top of list 322 

process commands 326 

refresh the screen image area from the data set 
list array 329 

update data set list array 324 

verify commands 325 

volume serial number syntax verification 319 

word finder 320 
input register contents 307 
input requirements 307 
linkage and error handling 307 
output register contents 308 
overview 307 
parameter lists 308 
DSCB (data set control block) 
described 3 
format-0 3 
format- 1 4 

format- 1 not found user exit 125 
format-2 4 
format-3 4 
fonnat-4 5 
fonnat-5 5 
format-6 5 
reading from VTOC by absolute device address 

coding example 32 

macro specif ications 31 

return codes 33 
reading from VTOC by data set name 

coding example 30 

macro specifications 29 

return codes 31 
DSECT expansions 

See CVT, lEFJFCBN, lEFUCBOB, TRKCALC 
DSN order 

initiating access to DSNs, DSCBs 50 
DSORG operand (DCB macro) 76 
dynamic device reconfiguration 
See DDR 



E 



ECB (event control block) 
used with EXCP macro 
used with XDAP macro 

end-of -extent appendage 
See EOE appendage 

end-of-volume 
See EOV macro 

EODAD operand (DCB macro) 

EOE appendage 71 

EOEA operand (DCB macro) 74 

EOV macro 

and Format- 1 DSCB not found 



68, 92 
104 



76 



125 
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used with EXCP macro 81-83 
used with XDAP macro 104 
ERNT (error table entries) 343 
error 

EXCP I/O 

recovery procedures 70 
VTOC 

processing 60 

recovering from system or user errors 60 
error messages 

See messages, CVAF VTOC error 
ERTB (ISMF error table) 343 
ET (ISMF environment table) 344 
event control block (ECB) 

See ECB 
examples 

of CVAFDIR macro 259-270 
of C VAFFBLT macro 27 1 -277 
of CVAFSEQ macro 277-292 
of CVAFTST and CVAFDSM macros 292-296 
of OPEN instaUation exit module 305 
EXCP (execute channel program) 
ABE appendage 71 
building list of fixed data areas 94 
channel programs 

appendage entry points 7 1 

appendage programming restrictions 71 

appendage register usage 7 1 

appendage returns 71 

appendages used with 71 

authorized appendage list 71 

completion processing 70 

execution 68-69 

I/O error handling 70 

including appendages in the system 7 1 

initiation 68-69 

modifying 70 

programming considerations 72-73 

translation by I/O supervisor 95 
CHE appendage 71 
control blocks used with 

DCB 68 

DEB 68 

ECB 68 

lOB 67 
EOE appendage 71 
IDAWs (indirect addressing words) 66 
in V=R address space 66 
PCI appendage 71 
requirements 67 

channel program 67 

control blocks 67 
SIO appendage 71 
EXCP macro 

advantages of using 64 
control blocks used with 

DCB 73-80 

DEB 92 

ECB 92 

lOB 89-91 
in problem programs 65 



in real storage 92 
in system control programs 64 
macro specification 81 
macros used with 
ATLAS 83 
CLOSE 83 
EOV 81-83 
OPEN 80-81 
multivolume data set requirement 80 
used with WATT macro 65 
EXCPVR macro 92-94 
executing chaimel programs 
in problem programs 65 
in real storage 92 
in system control programs 64 
exit routine 

See also DADSM pre/postprocessing exits 

See also data management ABEND installation exit 

See also DCB OPEN installation exit 

See also DCS pre/postcalculation exits 

See also format- 1 DSCB not found 

See also OPEN/EOV IBM-standard labeled tape 

security verification exit 
See also OPEN/EOV nonspecific tape mount 

request user exit 
functions possible 125 
EXLST operand (DCB macro) 76 
expiration date 
overriding 35 



B 



FCB (forms control buffer) image 

adding image to SYSl.IMAGELIB 219-221 

default image 

3262 printer 217 
4245 printer 217 
4248 printer 217 

inSYSLIMAGELIB 217-223 

JES2 support 225 

retrieving image from SYS 1 .IMAGELIB 222-223 
FCL (filter criteria list) 53 

entry format 56 

header format 54 
filter criteria list (FCL) 

See FCL 
fixing data areas with EXCPVR 92 
format 

of allocation retrieval area 144 

of allocation retrieval list 144 

of buffer list entry 46-47 

of buffer list header 45 

of CVPL (CVAF parameter list) 44 

of DADSM pre/postprocessing exit parameter 
list 125 

of DCS pre/postcalculation exit parameter 
list 125 

of LSPACE data return area 27 
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of LSPACE message return area 27 

of LSP ACE parameter list 24 

of OIEXL (OPEN installation exit parameter 

Ust) 125 
of VIER 10 
of VIER index entries 1 1 
of VTOC maps 15 
format 0-6 DSCB 3 
format-1 DSCB 

reading from VTOC 29 
format- 1 DSCB not found 

installation exit (IFGOEXOA) 125 
parameter list 125 
register contents 125 
return codes 125 
forms control buffer image 

See FCB image 
FOVT (format service vector table) 344 
free space 

on DASD voliune 

obtaining with LSPACE macro 20-29 
FUNCTN operand (TRKCALC macro) 162-170 



GDRB (ISMF global data repository block) 
GEN operand (MSGDISP macro) 197 
GTF trace of CVAF processing 
See CVPL 



345 



H 



high-speed 3480 positioning 149 



Q 



I/O devices 

characteristics 129 
IDAL (indirect data address list) 95-97 
ID AW (indirect addressing word) 

requirements 66 
IE AAPPOO, authorized appendage list 7 1 
lEBUPDTE program 

SYSl.PARMLIB 

use in Usting appendages in 71 
lECPCNVT (relative track address to actual track 

address conversion routine) 106 
lECPRLTV (actual track address to relative track 

address conversion routine) 107 
lECOSCRl (sector conversion routine) 108 
lEFJFCBN macro 128 
lEFUCBOB macro 128 



lEHATLAS program 85 

lEHLIST program 61 

lEPL (DADSM pre/postprocessing exit parameter 

list) 125 
IFGOEXOA program 

See format-1 DSCB not found 
IFGOEXOB program 

See DCB OPEN installation exit 
IFG0199I program 

See data management ABEND installation exit 
IGBDCSXl 

See DCS precalculation exit 
IGBDCSX2 

See DCS postcalculation exit 
IGGPOSTO program 

See DADSM pre/postprocessing exits 
IGGPREOO program 

See DADSM pre/postprocessing exits 
IGGUCSIT macro 213 
IHAARL macro 

specification 143 
IMNT (IMTT entries) 346 
IMSK operand (DCB macro) 76 
IMTT (ISMF inter module trace table) 345 
indexed VTOC 

compared to nonindexed 16 

initiating access to DSCBs 50 
indexing feature for 321 1 226 
indirect addressing word (IDAW) 

See IDAW 
indirect data address list (IDAL) 

See IDAL 
initializing DASD volumes 18 
interruption handling procedures 
lOB (input/output block) 

chain modification 161 

fields with EXCP macro 

fields with XDAP macro 

used with EXCP macro 
lOBAD operand (DCB macro) 77 
lOBSENS fields with ATLAS macro 85 



70 



89-91 
105 
67 



a 



JES2 

Printer support 225-226 
JFCB (job file control block) 
See also RDJFCB macro 
macros used with 
IHAARL 143 
OPEN 148-149 
RDJFCB 137-140 
mapping macro 128 
modifying 125, 136-150 
precautions 137 
job fUe control block (JFCB) 
See JFCB 
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K 



K operand (TRKC ALC macro) 1 65 , 1 66 
KEYLEN operand (DCB macro) 79 







LABEL operand (DD statement) 

password protected data set 1 1 2, 1 1 3 
library character set modules 203 
LIST operand 

CVT macro 129 
ffiFJFCBN macro 128 
ffiFUCBOB macro 128 
locate record CCW 

in EXCP processing 69 
LOGB (ISMF log buffer) 346 
LPAP (line operator table - application table) 347 
LPCB (list panel cursor control block) 347 
LPPL (line operator processor parameter list) 348 
LSP ACE macro 20-29 
coding example 

list and execute forms 29 
using data return area 28 
using message return area 28 
data return area 
format 27 
message return area 

format 27 
parameter list 

format 24 
return codes 25 



M 



MACRF=(E) operand (DCB macro) 
macros, data management 
See also CVAFDIR macro 
See also CVAFDSM macro 
See also CVAFFBLT macro 
See also CVAFSEQ macro 
See also CVAFTST macro 
ATLAS 83 
CAMLST 

with RENAME operand 
with SCRATCH operand 
with SEARCH operand 



74 



38-41 
33-37 
29-31 



with SEEK operand 31-33 
CLOSE 

used with EXCP macro 83 

used with XDAP macro 104 
CVAF (VTOC access) 

uses 42 
CVT 129 



DCB 73-80 
DEBCHK 152-155 
DEVTYPE 129-135 
EOV 

and Format- 1 DSCB not found 125 

used with EXCP macro 81-83 

used with XDAP macro 104 
EXCP 81 
EXCPVR 92-94 
lEFJFCBN 128 
ffiFUCBOB 128 
LSPACE 20-29 
MSGDISP 184-201 
OBTAIN 29-33 
OPEN 

and Format- 1 DSCB not found 125 

forJFCB 149 

for modified JFCB 148 

used with EXCP macro 80-8 1 
PARTREL 170-174 
PROTECT 116-124 
PURGE 156 
RDJFCB 136-140 
REALLOC 174-183 
RENAME 38-41 
RESTORE 156 

specification 161 
SCRATCH 33 
TRKCALC 162-170 
used with XDAP macro 100-101 
XDAP 99-103 
maintaining 124 

See also PROTECT macro 
PASSWORD data set 1 16-124 
VTOC (volume table of contents) 19-41 
mapping macros 
CVT 129 
ffiFJFCBN 128 
ffiFUCBOB 128 
maps of allocated space 

for cylinders and tracks 12 
for DSCBs 15 
for VIRs 14 
MAXSIZE operand (TRKCALC macro) 164, 166 
messages 

CVAF VTOC error 

descriptor codes 298 

programmer response 298 

return codes 298-303 

routing codes 298 

system action 297 

text and explanation 297 

when issued 297 
MF operand 

DEBCHK macro 155 
TRKCALC macro 165-167 
MODE operand 

EOV macro 82 
MODE operand (DCB macro) 80 
modifying 

channel program during execution 70 
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lOB chain 161 

JFCB 136, 150 

in OPEN installation exit 125 
MOUNT operand (MSGDISP macro) 184 
MSGDISP macro 184 

displaying a demount message 191 

displaying a mount message 184 

displaying a ready message 189 

displaying a verify message 187 

providing the full range of display options 197 

resetting the message display 194 

return codes 200 
multivolume data set 

processing with EXCP macro 80 



OUTINX operand (OPEN macro) 
output data set 

maintaining DCBBLKCT field 



76 



74 



N 



name 

VTOC index 8 
nonindexed VTOC 

compared to indexed 16 
nonpageable address space, V= V 69 
NOPWREAD protection-mode indicator 1 1 6 
NO WRITE protection-mode indicator 116 



o 



OADCL (data management ABEND installation exit 

parameter list) 125 
OBTAIN macro 29-31 
obtaining a sector number (RPS devices) 108 
OIEXL (OPEN installation exit parameter list) 125 
OPEN installation exit 

See DCB OPEN installation exit 
OPEN macro 

and DEQ at demount facility 147 
and Format- 1 DSCB not found 125 
getting control from 125 
TYPE=J 

example 141 
invoking 147 
specification 149 
used with EXCP macro 

dummy data set restriction 80 
procedures performed 80 
used with XDAP macro 101 
with modified JFCB 148 
open processing 

after IFGOEXOB gets control 125 
and OPEN installation exit 1 25 
before IFGOEXOB gets control 125 
opening a VTOC 

restriction on changing contents 140 
OPENJ (OPEN, TYPE=J) macro 

specification 148 
OPTCD=Z operand (DCB macro) 76 



s 



page boundary 95 
page-fix 

appendage 

See PGFX appendage 

list processing 94 
pageable address space, VsR 66 
parameter list 

See CVPL 

See DADSM pre/postprocessing exits 

See data management ABEND installation exit 

See DCB OPEN installation exit 

See DCS pre/postcalculation exits 

See format- 1 DSCB not found installation exit 
partial release via JFCB modification 125 

in OPEN installation exit 
example 305 
PARTREL macro 170-174 

return codes 174 
password 

See also PROTECT macro 

control 116 

counter maintenance 115 

data set concatenation 115 

deleting or renaming a protected data set 115 

parameter list 118 
ADD a record 118 
DELETE a record 122 
LIST a record 123 
REPLACE a record 120 

protecting data sets 1 1 1 - 1 24 

protecting tape data sets 114 

protecting VTOC indexes 1 8 

protection mode indicator 116 

record 113 

protection mode indicator 113 

secondary 116 

standard label restriction 112 

terminating protection 114 

volume switching 115 
PASSWORD data set 

characteristics 116 

creating 113 

protected data set records in 116 

requirements 113 
PCCB (panel cursor control block) 349 
PCI appendage 71 
PCI operand (DCB macro) 74 
PCIA operand (DCB macro) 74 
PGFX appendage 94 
physical sequential access, initiating 5 1 
PIRL (purged I/O restore list) 

use in restoring I/O requests 161 
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posting completion code in ECB 

following use of EXCP macro 92 

following use of XDAP macro 104 
postprocessing 

See DADSM pre/postprocessing exits 
PREFIX operand (ffiFUCBOB macro) 128 
preprocessing 

See DADSM pre/postprocessing exits 
printer image 

See UCS image 
program controlled interruption appendage 

See PCI appendage 
PROTECT macro 

See also password 

parameter list 122 
ADD function 118 
DELETE function 122 
LIST function 123 
REPLACE function 120 

protection mode indicator 116 

return codes 124 

syntax 117 

use with PASSWORD dataset 111-123 
protecting 

VTOC 

with RACE 17 

VTOC index 

with passwords 18 
with RACE 17 
PRTSP operand (DCB macro) 80 
PURGE macro 

adding to macro library 156 

definition 156 

parameter list 158 

return codes 160 

specification 158 
purged I/O restore list 

SeePIRL 
PVT (ISMF profile variable table) 349 
PVTV (ISMF profile variable table variables) 350 
PWRE AD protection-mode indicator 116 
PWWRTTE protection-mode indicator 116 



QSAM (queued sequential access method) 
defaulting buffer mmiber 1 25 



H 



R operand (TRKCALC macro) 165, 166 
RACE 

protecting VTOCs and VTOC indexes 

renaming a data set 38 

scratching a data set 34 
RDJFCB 



17 



retrieving allocation information 143 
RDJFCB macro 

allocation retrieval area 
format 144 

allocation retrieval list 
format 144 

coding example 138 

common coding errors 139 

description 137 

exit list entry for 
type '07' 139 
type '13' 142 

invoking DEQ at demount 147 

retrieving allocation information 
coding example 145 

return codes 139 

security 140 

specification 137 

use by authorized programs 141 

with MSS virtual volumes 140 
RDY operand (MSGDISP macro) 189 
reading 

and modifying a JFCB 1 36- 1 40 

data from index maps 49 

DSCBs 

directly by data set name 48 
directly by DSCB location 48 
sequentially 50 

VIRs 48-49 
reading sets of DSCBs 

with CVAF filter service 52 
READPSWD module 113 
REALLOC macro 174-183 

return codes 181 
RECFM operand (DCB macro) 77 
recovering 

from errors 60 

from permanent DASD I/O error 
See ATLAS macro 
register 

contents at return from DCB OPEN exit 125 

conventions for appendages 71 

usage by conversion routines 

actual to relative routine 107 
relative to actual routine 106 

usage by CVAF routines 43 

usage by I/O supervisor 71 
REGSAVE operand (TRKCALC macro) 165, 167 
related 

channel program 71 

requests 71 
releasing DASD space 5 

REMOVE operand (TRKCALC macro) 164, 166 
RENAME macro 

dummy module 227 

return codes 40 

specification 38 
renaming a data set 

coding example 39 

macro specification 38 

with password protection 41 
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WRITE protection mode indicator 41 
REPOS operand (DCB macro) 74 
requesting partial release via JFCB modification 125 
requirements 

for APF 18 

for DASD copy, restore, operations 
indexed VTOC 18 
nonindexed VTOC 18 
RESET operand (MSGDISP macro) 194 
Resource Access Control Facility 

See RACF 
RESTORE macro 

adding to macro library 156 

definition 156 

specification 161 
restore operation 

DASD volume 

indexed VTOC requirements 18 
nonindexed VTOC requirements 18 
restoring DASD volumes 18 
restoring iob chain 161 
restrictions 

when scratching, renaming, allocating 16 
return codes 

ATLAS macro 86 

CVAFDIR macro 238 

CVAFDSM macro 244 

CVAFFILT macro 249 

CVAFSEQ macro 256 

CVAFTST macro 258 

DEBCHK macro 155 

DEVTYPE macro 133 

from D ADSM allocation 1 8 1 

from DADSM exits 125 

from data management ABEND exit 125 

from DCB OPEN exit 125 

from DCS exits 125 

from format- 1 DSCB not found exit 125 

from lECPCNVT convert routine 107 

LSP ACE macro 25 

MSGDISP macro 200 

OBTAIN macro 

when reading from VTOC by absolute device 

address 33 
when reading from VTOC by data set 
name 31 

PARTREL macro 174 

RDJFCB macro 139 

RE ALLOC macro 181 

RENAME macro 40 

SCRATCH macro 36 

TRKCALC macro 169 

with CVAF VTOC error message 298-303 
RKDD operand (TRKCALC macro) 165, 166 
RPS (rotational position sensing) 

devices 

used with XDAP macro 108 



SCRATCH macro 

coding example 35 

dummy module 227 

general description 33 

return codes 36 

status codes 37 
scratching a data set 

when volimie not moimted 34 
secondary 

passwords 116 

space data 

updating in OPEN mstaUation exit 125 
updating in OPEN installation exit, 
example 305 
sector, address in XDAP macro 

specification 102 

with RPS devices 108 
securing 

a VTOC 

with passwords 18 
with RACF 17 

a VTOC index 

See also protecting a VTOC index 
with RACF 17 
seek CCW 

in EXCP processing 69 
SELB (select block) 351 
serialization, CVAF 42 
SIO appendage 71 

for EXCPVR 94 
SIOA operand (DCB macro) 74 
space map 

of allocated cylinders and tracks 1 2 

of allocated DSCBs 12 

of allocated VIRs 12 
SRVT (ISMF common service routine vector 

table) 352 
SSCH (start subchannel) instruction 

how used in I/O process 64 

when issued by lOS 69 
STACK operand (DCB macro) 80 
stand-alone seek 69 

standard label restriction, password data sets 112 
start-I/O appendage 

See SIO appendage 
start subchannel instruction 

See SSCH 
status codes 

SCRATCH macro 37 
system control blocks 125 

mapping macros for 
CVT 129 

JFCB (lEFJFCBN) 128 
UCB (lEFUCBOB) 128 
system macro instructions 127 
SYSl .IMAGELIB data set 

adding a UCS image to 204 
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maintaining 203 
UCS image tables in 
UCS images in 204 



209 







95 
69 
95 



tape volumes 

DEQ at demount facility 147 
testing for a VTOC index 257 
trace of CVAF processing 61 
track 

assigning an alternate 
with ATLAS 83 

calculating capacity 1 62- 170 
translation of channel program 

by I/O supervisor 

in V=R address space 
in V=V address space 
in your own program 
TRKBAL operand (TRKCALC macro) 

example 169 
TRKCALC macro 1 62- 1 70 

return codes 169 
TRKCAP operand (TRKCALC macro) 

example 169 
TRTCH operand (DCB macro) 79 
TYPE operand 

DEBCHK macro 152 

in OPEN macro 148 

TRKCALC macro 164, 166 
examples 169 
TYPE=J (OPEN macro) 148 



162-163 



163-164 



u 



UCB (unit control block) 
getting information from 

See DEVTYPE macro 
mapping macro 131 
operand of TRKCALC macro 1 64, 1 66 
UCS (universal character set) 
image 

adding to SYS 1 .IMAGELIB 204 

examples of adding to SYSl.IMAGELIB 206 

for JES2 225 

verifying 215-217 
image table 

adding aliases 213 

adding image names 213 

contents 211 

entry format 209 

examples of adding to 216 

modifying entries 213 

structure 209 
unit check with ATLAS macro 85 
unit control block (UCB) 



See UCB 
universal character set (UCS) 

See UCS 
updating secondary space data 

in OPEN installation exit 
example 305 
user exit routine 

See exit routine 



125 



s 



V=R address space 

EXCP operations 66 
V=V address space 69 
vaUdating the DEB (DEBCHK) 151-155 
VERIFY operand (MSGDISP macro) 187 
VIER (VTOC index entry record) 
characteristics 9 
contents of fields 9 
format 10 
function 8 

how chained together 12 
how to find a format- 1 DSCB 12 

special cases 12 
index entry 

format 1 1 
when created 1 1 
Vm (VTOC index record) 
kinds 8 
length 8 
virtual IDAW (indirect addressing word) 66 
VDCM (VTOC index map) 
bit maps 

of allocated DSCBs 14 
of allocated VIRs 14 
format 15 
function 14 
maps of allocated space 
for VIRs 14 
VMDS (VTOC map of DSCBs) 
format 15 

maps of allocated space 
function 15 
volume 

identification to CVAF 42 
switching 141 
table of contents 
See VTOC 
VPSM (VTOC pack space map) 
bit maps 

of allocated cylinders and tracks 12 
description 12 
format 15 
function 12 
space map 

of allocated DSCBs 12 
of allocated VIRs 12 
VTOC (volume table of contents) 
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access macros 

See CVAFDIR macro 
See CVAFDSM macro 
See CVAFFILT macro 
See CVAFSEQ macro 
See CVAFTST Macro 

creating 17 

description 1 

example 8 

how to locate 1 

index 

contents 8 

creating 17 

description 8 

how to list 61 

name 8 

password protection 18 

protecting with RACF 17 

relationship to VTOC 9 

structure 9 

testing for 257 

index entry record (VIER) 
SeeVIER 

index map (VDCM) 
SeeVrXM 

index record (VIR) 
SeeVIR 

initializing and maintaining 

maintaining 

description 1 
index 19, 33 
using OBTAIN macro 
using RENAME macro 
using SCRATCH macro 

map of DSCBs (VMDS) 
SeeVMDS 

pack space map (VPSM) 
See VPSM 

protecting 

with RACF 17 



X 



17 



29-33 
38-41 
33-37 



XDAP 

channel program 105 

macro 

CLOSE macro used with 104 
control blocks used with 104 
DCB macro used with 100 
EOV macro used with 104 
OPEN macro used with 101 
requirements 100-101 
specification 101-103 
XENDA operand (DCB macro) 75 



Numerics 



W 



1403 printer 

JES2 support 225 
31 -bit ID AW (indirect addressing word) 66 
3203 printer 

JES2 support 226 

output from DEVTYPE 134 
3211 printer 

indexing feature 226 

JES2 support 226 
3262 Model 5 printer 

default FCB image 217 

UCS image table for 209, 2 1 2 
3480 tape drive 

high-speed positioning 149 

output from DEVTYPE macro 1 34 
3800 printer 

output from DEVTYPE macro 134 
4245 printer 

default FCB image 217 

output from DEVTYPE macro 1 34 

UCS image table 209 
4248 printer 

default FCB image 217 

UCS image table 209 



WAIT macro 

used with EXCP macro 65 
writing 

DSCBs 49 

VIRs 49 
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